From e1ce7ceb6fa34f41d804aa6db155bb2faf79b5f3 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 01/16] Refactored ExtraOptionConfigs to BaseConfiguration
 pattern with ActiveModel::Validations - fixes #986

---
 app/helpers/application_helper.rb             |    4 +-
 app/models/concerns/options_handler.rb        |   79 +-
 .../option_configs/activity_log_options.rb    |   61 +-
 .../base_named_configuration.rb               |   71 +
 .../base_configuration.rb                     |  218 ++
 .../extra_option_configs/batch_trigger.rb     |   33 +
 .../extra_option_configs/caption_before.rb    |   47 +
 .../extra_option_configs/config_base.rb       |  106 +
 .../extra_option_configs/config_trigger.rb    |   43 +
 .../extra_option_configs/creatable_if.rb      |   25 +
 .../extra_option_configs/db_configs.rb        |   16 +
 .../extra_option_configs/dialog_before.rb     |   70 +
 .../extra_option_configs/e_sign_config.rb     |   57 +
 .../extra_option_configs/editable_if.rb       |   25 +
 .../extra_option_configs/embed.rb             |   87 +
 .../extra_option_configs/field_configs.rb     |  125 +
 .../extra_option_configs/field_options.rb     |   36 +
 .../extra_option_configs/fields.rb            |   23 +
 .../extra_option_configs/filestore.rb         |   24 +
 .../extra_option_configs/if_condition.rb      |   37 +
 .../extra_option_configs/label.rb             |   32 +
 .../extra_option_configs/labels.rb            |   13 +
 .../extra_option_configs/nfs_store_config.rb  |   67 +
 .../extra_option_configs/preset_fields.rb     |   13 +
 .../extra_option_configs/references.rb        |  164 ++
 .../extra_option_configs/save_action.rb       |   45 +
 .../extra_option_configs/save_trigger.rb      |   85 +
 .../extra_option_configs/set_variable.rb      |   75 +
 .../extra_option_configs/show_if.rb           |   41 +
 .../extra_option_configs/showable_if.rb       |   25 +
 .../extra_option_configs/trigger_tasks.rb     |   46 +
 .../extra_option_configs/valid_if.rb          |   61 +
 .../extra_option_configs/view_options.rb      |   24 +
 app/models/option_configs/extra_options.rb    |  557 +----
 .../validates/typed_attribute_validator.rb    |   14 +
 spec/models/calc_actions/calculate_spec.rb    |    6 +-
 .../dynamic_model_options_spec.rb             |   18 +-
 .../extra_option_configs_spec.rb              | 2099 +++++++++++++++++
 .../extra_options_clean_methods_spec.rb       | 1196 ++++++++++
 spec/models/save_triggers/notify_spec.rb      |    2 +-
 spec/support/activity_log_support.rb          |    2 +-
 41 files changed, 5249 insertions(+), 523 deletions(-)
 create mode 100644 app/models/option_configs/extra_option_configs/base_configuration.rb
 create mode 100644 app/models/option_configs/extra_option_configs/batch_trigger.rb
 create mode 100644 app/models/option_configs/extra_option_configs/caption_before.rb
 create mode 100644 app/models/option_configs/extra_option_configs/config_base.rb
 create mode 100644 app/models/option_configs/extra_option_configs/config_trigger.rb
 create mode 100644 app/models/option_configs/extra_option_configs/creatable_if.rb
 create mode 100644 app/models/option_configs/extra_option_configs/db_configs.rb
 create mode 100644 app/models/option_configs/extra_option_configs/dialog_before.rb
 create mode 100644 app/models/option_configs/extra_option_configs/e_sign_config.rb
 create mode 100644 app/models/option_configs/extra_option_configs/editable_if.rb
 create mode 100644 app/models/option_configs/extra_option_configs/embed.rb
 create mode 100644 app/models/option_configs/extra_option_configs/field_configs.rb
 create mode 100644 app/models/option_configs/extra_option_configs/field_options.rb
 create mode 100644 app/models/option_configs/extra_option_configs/fields.rb
 create mode 100644 app/models/option_configs/extra_option_configs/filestore.rb
 create mode 100644 app/models/option_configs/extra_option_configs/if_condition.rb
 create mode 100644 app/models/option_configs/extra_option_configs/label.rb
 create mode 100644 app/models/option_configs/extra_option_configs/labels.rb
 create mode 100644 app/models/option_configs/extra_option_configs/nfs_store_config.rb
 create mode 100644 app/models/option_configs/extra_option_configs/preset_fields.rb
 create mode 100644 app/models/option_configs/extra_option_configs/references.rb
 create mode 100644 app/models/option_configs/extra_option_configs/save_action.rb
 create mode 100644 app/models/option_configs/extra_option_configs/save_trigger.rb
 create mode 100644 app/models/option_configs/extra_option_configs/set_variable.rb
 create mode 100644 app/models/option_configs/extra_option_configs/show_if.rb
 create mode 100644 app/models/option_configs/extra_option_configs/showable_if.rb
 create mode 100644 app/models/option_configs/extra_option_configs/trigger_tasks.rb
 create mode 100644 app/models/option_configs/extra_option_configs/valid_if.rb
 create mode 100644 app/models/option_configs/extra_option_configs/view_options.rb
 create mode 100644 app/models/validates/typed_attribute_validator.rb
 create mode 100644 spec/models/option_configs/extra_option_configs_spec.rb
 create mode 100644 spec/models/option_configs/extra_options_clean_methods_spec.rb

diff --git a/app/helpers/application_helper.rb b/app/helpers/application_helper.rb
index c41dfcb3c1..8ad8174922 100644
--- a/app/helpers/application_helper.rb
+++ b/app/helpers/application_helper.rb
@@ -214,7 +214,9 @@ def show_caption_before(key, captions, mode: nil, no_sub: nil, ignore_missing: t
 
     mode ||= action_name == 'new' ? :new : :edit
     caption = captions[key]
-    caption = caption[:"#{mode}_caption"] || caption[:caption] || '' if caption.is_a?(Hash)
+    if caption.is_a?(Hash) || caption.is_a?(OptionConfigs::BaseNamedConfiguration)
+      caption = caption[:"#{mode}_caption"] || caption[:caption] || ''
+    end
     if @form_object_instance && !no_sub
       caption = Formatter::Substitution.substitute(caption, data: @form_object_instance, tag_subs: nil,
                                                             ignore_missing:)
diff --git a/app/models/concerns/options_handler.rb b/app/models/concerns/options_handler.rb
index f0ed1c0175..4130b9ceaf 100644
--- a/app/models/concerns/options_handler.rb
+++ b/app/models/concerns/options_handler.rb
@@ -172,6 +172,72 @@ def configure_hash(config_item_name, with:)
       ch.const_set(config_item_name.ns_camelize, c)
     end
 
+    #
+    # Class method for declaring that a class stores a single direct value of a given type.
+    # This provides a consistent mechanism for defining configuration classes that hold
+    # one typed value (e.g., a string, array, hash, or if_condition) rather than
+    # multiple named attributes.
+    #
+    # The type metadata allows future validation and coercion. Currently supported types:
+    # - :string  — stores a String value
+    # - :array   — stores an Array value
+    # - :hash    — stores an arbitrary Hash value
+    # - :if_condition — stores a conditional Hash (for access/validation conditions)
+    #
+    # Example:
+    #   class Label < SomeBase
+    #     configure_direct :label, type: :string
+    #   end
+    #
+    # @param [Symbol] config_item_name - the name of the configuration item
+    # @param [Symbol] type - the value type (:string, :array, :hash, :if_condition)
+    def configure_direct(config_item_name, type:)
+      attr_accessor(config_item_name) unless method_defined?(config_item_name)
+
+      add_option_type(:direct, config_item_name)
+
+      # Store type metadata for future validation/coercion
+      @direct_types ||= {}
+      @direct_types[config_item_name] = type
+    end
+
+    #
+    # Returns the registered direct types for this class.
+    # @return [Hash{Symbol => Symbol}] mapping of attribute name to type
+    def direct_types
+      @direct_types || {}
+    end
+
+    #
+    # Class method for declaring a typed attribute whose value is an instance of
+    # a class inheriting from BaseConfiguration.
+    #
+    # When the including class is initialized with a hash configuration, the
+    # attribute value is automatically set by passing the corresponding hash
+    # entry to the type class constructor.
+    #
+    # @param [Symbol] config_item_name - the attribute name
+    # @param [Class] type - a class inheriting from BaseConfiguration that
+    #   accepts a hash in its constructor
+    #
+    # @example
+    #   configure_typed_attribute :creatable_if, type: ExtraOptionConfigs::IfCondition
+    def configure_typed_attribute(config_item_name, type:)
+      attr_accessor(config_item_name) unless method_defined?(config_item_name)
+
+      add_option_type(:typed, config_item_name)
+
+      @typed_attribute_types ||= {}
+      @typed_attribute_types[config_item_name] = type
+    end
+
+    #
+    # Returns the registered typed attribute types for this class.
+    # @return [Hash{Symbol => Class}] mapping of attribute name to type class
+    def typed_attribute_types
+      @typed_attribute_types || {}
+    end
+
     #
     # List of configuration items having child options.
     # Each represents the name of an accessor attribute in this model
@@ -180,7 +246,9 @@ def option_types
       @option_types ||= {
         multi: [],
         simple: [],
-        hash: []
+        hash: [],
+        direct: [],
+        typed: []
       }
     end
 
@@ -303,6 +371,7 @@ def setup_from_hash_config
     setup_all_options_multi hash_configuration
     setup_all_options_simple hash_configuration
     setup_all_options_hash hash_configuration
+    setup_all_options_typed hash_configuration
 
     hash_configuration
   end
@@ -322,6 +391,14 @@ def setup_all_options_simple(hash_configuration)
     end
   end
 
+  def setup_all_options_typed(hash_configuration)
+    self.class.option_types[:typed]&.each do |option_type|
+      type_class = self.class.typed_attribute_types[option_type]
+      config_val = hash_configuration[option_type]
+      send("#{option_type}=", type_class.new(config_val))
+    end
+  end
+
   def setup_all_options_hash(hash_configuration)
     self.class.option_types[:hash].each do |option_type|
       setup_options_hash(hash_configuration, option_type)
diff --git a/app/models/option_configs/activity_log_options.rb b/app/models/option_configs/activity_log_options.rb
index 9d973495a7..3a8093f9a2 100644
--- a/app/models/option_configs/activity_log_options.rb
+++ b/app/models/option_configs/activity_log_options.rb
@@ -10,14 +10,21 @@ class ActivityLogOptions < ExtraOptions
     ValidNfsStoreCanPerformKeys = %i[download_if view_files_as_image_if view_files_as_html_if send_files_to_trash_if
                                      move_files_if user_file_actions_if].freeze
 
+    def self.config_class_registry
+      super.merge(
+        e_sign: ExtraOptionConfigs::ESignConfig,
+        nfs_store: ExtraOptionConfigs::NfsStoreConfig
+      )
+    end
+
     def self.add_key_attributes
-      %i[e_sign nfs_store]
+      []
     end
 
     attr_accessor(*key_attributes)
 
     def initialize(name, config, parent_activity_log)
-      super(name, config, parent_activity_log)
+      super
 
       if @config_obj.disabled
         Rails.logger.info "configuration for this activity log has not been enabled: #{@config_obj.table_name}"
@@ -26,57 +33,11 @@ def initialize(name, config, parent_activity_log)
       raise FphsException, 'extra log options name: property can not be blank' if self.name.blank?
 
       # Activity logs have some predefined captions. Set these up.
-      if caption_before && !caption_before.is_a?(Hash)
+      if caption_before && !caption_before.is_a?(Hash) && !caption_before.is_a?(ExtraOptionConfigs::BaseConfiguration)
         raise FphsException, 'extra log options caption_before: must be a hash of {field_name: caption, ...}'
       end
 
       init_caption_before
-
-      clean_e_sign_def
-      clean_nfs_store_def
-    end
-
-    def clean_nfs_store_def
-      return unless nfs_store
-
-      can_perform = nfs_store[:can]
-
-      unless valid_config_keys?(nfs_store, ValidNfsStoreKeys)
-        failed_config :nfs_store,
-                      "nfs_store contains invalid keys #{nfs_store.keys} - " \
-                      "expected only #{ValidNfsStoreKeys}"
-      end
-
-      unless can_perform.nil? || valid_config_keys?(can_perform, ValidNfsStoreCanPerformKeys)
-        failed_config :nfs_store__can,
-                      "nfs_store.can contains invalid keys #{can_perform.keys} - " \
-                      "expected only #{ValidNfsStoreCanPerformKeys}"
-      end
-
-      NfsStore::Config::ExtraOptions.clean_def nfs_store
-    end
-
-    def clean_e_sign_def
-      return unless e_sign
-
-      # Set up the structure so that we can use the standard reference methods to parse the configuration
-      e_sign[:document_reference] = { item: e_sign[:document_reference] } unless e_sign[:document_reference][:item]
-      e_sign[:document_reference].each_value do |refitem|
-        # Make all keys singular, to simplify configurations
-        refitem.transform_keys! do |k|
-          new_k = k.to_s.singularize.to_sym
-        end
-
-        refitem.each do |mn, conf|
-          to_class = ModelReference.to_record_class_for_type(mn)
-
-          refitem[mn][:to_record_label] = conf[:label] || to_class&.human_name
-          if to_class&.respond_to?(:no_master_association)
-            refitem[mn][:no_master_association] = to_class.no_master_association
-          end
-          refitem[mn][:to_model_name_us] = to_class&.to_s&.ns_underscore
-        end
-      end
     end
 
     # A list of all fields defined within all the individual activity definitions. This does not include
@@ -129,7 +90,7 @@ def init_caption_before
         protocol_id: {
           caption: "Select the protocol this #{curr_name} is related to. A tracker event will be recorded under this protocol."
         },
-        "set_related_#{item_type}_rank".to_sym => {
+        "set_related_#{item_type}_rank": {
           caption: "To change the rank of the related #{item_type.to_s.humanize}, select it:"
         }
       }
diff --git a/app/models/option_configs/base_named_configuration.rb b/app/models/option_configs/base_named_configuration.rb
index 30fa1f53ea..5cbba29c92 100644
--- a/app/models/option_configs/base_named_configuration.rb
+++ b/app/models/option_configs/base_named_configuration.rb
@@ -4,6 +4,61 @@ class BaseNamedConfiguration < OptionConfigs::BaseOptions
 
     attr_accessor :owner, :use_hash_config
 
+    #
+    # Hash-like access to configuration attributes by key name.
+    # Enables backward compatibility with code that expects Hash-like access
+    # on individual named configuration items, e.g. `named_config[:caption]`
+    # @param [Symbol | String] key - the attribute name
+    # @return [Object] the attribute value, or nil if not recognized
+    def [](key)
+      sym_key = key.to_sym
+      return nil unless respond_to?(sym_key)
+
+      send(sym_key)
+    end
+
+    #
+    # Convert all configured attributes to a plain Hash.
+    # Mirrors OptionsHandler::Configuration#to_h for named configurations.
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      res = {}
+      self.class.option_types[:simple].each { |k| res[k] = send(k) }
+      res
+    end
+
+    alias to_hash to_h
+
+    # Hash-compatible dig for nested access on named configurations.
+    # @param keys [Array<Symbol>] nested key path
+    # @return [Object, nil]
+    def dig(*keys)
+      first = keys.shift
+      val = self[first]
+      return val if keys.empty? || val.nil?
+
+      val.respond_to?(:dig) ? val.dig(*keys) : nil
+    end
+
+    #
+    # Equality comparison: compare as plain Hash for backward compatibility
+    # with code that previously stored raw Hashes instead of NamedConfiguration objects.
+    # @param other [Object] value to compare against
+    # @return [Boolean]
+    def ==(other)
+      return to_h == other if other.is_a?(Hash)
+
+      super
+    end
+
+    #
+    # Return a Hash containing only non-nil attribute values.
+    # Useful for serialization where nil values should be omitted.
+    # @return [Hash{Symbol => Object}]
+    def filtered_hash
+      to_h.reject { |_k, v| v.nil? }
+    end
+
     def config_text
       return super unless owner
 
@@ -24,5 +79,21 @@ def persisted?
 
       owner.persisted?
     end
+
+    # Check for keys in hash_configuration that don't match any declared
+    # configure_attributes. Reports each unrecognized key as a warning
+    # on the owner (BaseConfiguration) via failed_config.
+    # Called after setup_from_hash_config so that declared attributes are known.
+    def validate_recognized_keys
+      return unless hash_configuration.is_a?(Hash)
+      return unless owner&.respond_to?(:failed_config, true)
+
+      recognized = self.class.option_types[:simple].to_set
+      hash_configuration.each_key do |key|
+        next if recognized.include?(key)
+
+        owner.send(:failed_config, key, "unrecognized attribute '#{key}'", level: :warn)
+      end
+    end
   end
 end
diff --git a/app/models/option_configs/extra_option_configs/base_configuration.rb b/app/models/option_configs/extra_option_configs/base_configuration.rb
new file mode 100644
index 0000000000..00ebf47223
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/base_configuration.rb
@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Base class for field-keyed configuration classes that follow the
+    # BaseConfiguration/NamedConfiguration pattern.
+    #
+    # Inherits from OptionConfigs::BaseConfiguration and provides:
+    # - Hash initialization: `ConfigClass.new({ field1: value1, field2: value2 })`
+    # - Hash-like interface: `[]`, `[]=`, `merge!`, `keys`, `each`, `blank?`, `key?`
+    # - Backward compatibility: `symbolize_keys`, `as_json`, `to_json`
+    # - Error reporting: `failed_config` stores errors locally for ExtraOptions to collect
+    #
+    # Subclasses may:
+    # - Define a NamedConfiguration inner class for structured field values
+    # - Override `add_named_configuration` for preprocessing (call super with processed value)
+    # - Define `self.prepare_config(raw, parent)` for pre-initialization context needs
+    # - Override `self.store_processed_value?` to return true for classes that should
+    #   store their processed attribute value on the parent ExtraOptions instead of the object
+    class BaseConfiguration < OptionConfigs::BaseConfiguration
+      include Enumerable
+
+      # Provide a model_name that handles anonymous subclasses.
+      # ActiveModel::Name requires a class name; anonymous classes have nil.
+      # Falls back to 'Configuration' for anonymous classes.
+      def self.model_name
+        @_model_name ||= ActiveModel::Name.new(self, nil, name || 'Configuration')
+      end
+
+      # Whether the registry should store the processed attribute value (not the object)
+      # on the parent ExtraOptions. Override to return true in subclasses that act as
+      # value preprocessors (e.g. Label, Fields, *_if classes).
+      # @return [Boolean]
+      def self.store_processed_value?
+        false
+      end
+
+      # Initialize with just a hash config (no owner required).
+      # Bypasses the parent's owner-based initialization since these
+      # config classes don't persist independently — managed by ExtraOptions.
+      # @param [Hash, Array, nil] hash_config - raw configuration (usually a Hash keyed by field name,
+      #   but may be an Array for classes like TriggerTasks that accept list values)
+      def initialize(hash_config = {})
+        self.errors = ActiveModel::Errors.new(self)
+        self.config_errors = []
+        self.config_warnings = []
+        self.configurations = {}
+        self.hash_configuration = hash_config.is_a?(Hash) ? hash_config.symbolize_keys : (hash_config || {})
+        setup_named_configurations
+        run_validations
+      end
+
+      # Default setup: iterate hash entries and create configurations.
+      # Subclasses override for custom preprocessing.
+      # @return [void]
+      def setup_named_configurations
+        hash_configuration.each do |k, v|
+          add_named_configuration(k.to_sym, v)
+        end
+      end
+
+      # Override parent's add_named_configuration to pass value directly
+      # (not wrapped in {key => value}).
+      # For classes with NamedConfiguration and Hash values, creates a NamedConfiguration.
+      # For classes without (or with non-Hash values), stores the value directly.
+      # @param [Symbol] sym_key - field name
+      # @param [Object] value - field configuration value
+      def add_named_configuration(sym_key, value)
+        configurations[sym_key] = if self.class.const_defined?(:NamedConfiguration) && value.is_a?(Hash)
+                                    nc = self.class::NamedConfiguration.new(self, use_hash_config: value)
+                                    nc.validate_recognized_keys
+                                    nc
+                                  else
+                                    value
+                                  end
+      end
+
+      # Assign a field configuration by key.
+      # @param [Symbol | String] key - field name
+      # @param [Object] value - field configuration
+      def []=(key, value)
+        add_named_configuration(key.to_sym, value)
+      end
+
+      # Merge a plain hash of field configurations.
+      # @param [Hash] other_hash - hash of { field_name: config } entries
+      # @return [self]
+      def merge!(other_hash)
+        other_hash.each { |k, v| add_named_configuration(k.to_sym, v) }
+        self
+      end
+
+      # Return symbol keys of all configured fields.
+      # @return [Array<Symbol>]
+      def keys
+        configurations.keys
+      end
+
+      # Check if a field key exists.
+      # @param [Symbol | String] key
+      # @return [Boolean]
+      def key?(key)
+        configurations.key?(key.to_sym)
+      end
+
+      alias has_key? key?
+
+      # Returns true when no fields are configured.
+      def blank?
+        configurations.blank?
+      end
+
+      # Returns true when no fields are configured (Hash-compatible).
+      def empty?
+        configurations.empty?
+      end
+
+      # Hash-compatible dig for nested access.
+      # Delegates to configurations hash then chains dig on the result.
+      # @param keys [Array<Symbol>] nested key path
+      # @return [Object, nil]
+      def dig(*keys)
+        first = keys.shift
+        val = configurations[first.to_sym]
+        return val if keys.empty? || val.nil?
+
+        val.respond_to?(:dig) ? val.dig(*keys) : nil
+      end
+
+      # Hash-compatible iteration methods delegated to configurations.
+      delegate :each_value, :each_key, :each_pair, :values, :size, :length,
+               :any?, :all?, :none?, :count, :to_a, :map, to: :configurations
+
+      # Delegates to configurations hash for iteration.
+      # Yields [key, value] pairs for iteration.
+      # @yield [Symbol, Object] field name and its configuration value
+      def each(&)
+        configurations.each(&)
+      end
+
+      # Override Enumerable#select to preserve Hash return type,
+      # matching the behavior of Hash#select/filter.
+      # @return [Hash]
+      def select(&)
+        configurations.select(&)
+      end
+
+      alias filter select
+
+      # Equality comparison: compare as plain Hash for backward compatibility
+      # with code that previously compared against Hash literals.
+      # @param other [Object] value to compare against
+      # @return [Boolean]
+      def ==(other)
+        return symbolize_keys == other if other.is_a?(Hash)
+
+        super
+      end
+
+      # Returns a plain Hash representation for backward compatibility.
+      # NamedConfiguration values are converted to filtered hashes;
+      # plain values are returned as-is.
+      # @return [Hash{Symbol => Object}]
+      def symbolize_keys
+        configurations.transform_values do |v|
+          v.respond_to?(:filtered_hash) ? v.filtered_hash : v
+        end
+      end
+
+      # JSON serialization producing the same format as the original plain hash.
+      # @return [Hash]
+      def as_json(options = nil)
+        symbolize_keys.as_json(options)
+      end
+
+      def to_json(*)
+        as_json.to_json(*)
+      end
+
+      # OptionsHandler persistence stubs — field-keyed configs don't store YAML independently
+      def config_text = nil
+
+      def config_text=(value); end
+
+      def save_options; end
+
+      def persisted? = false
+
+      protected
+
+      # Error reporting — stores errors locally.
+      # ExtraOptions collects these after initialization.
+      # @param [Symbol] type - error category
+      # @param [String] message - error description
+      # @param [Object] extra_details - additional context
+      # @param [Symbol] level - :error or :warn
+      def failed_config(type, message, extra_details: nil, level: :error)
+        target = (level == :warn ? config_warnings : config_errors)
+        target << { type:, message:, extra_details: }
+      end
+
+      private
+
+      # Bridge ActiveModel::Validations errors into config_errors.
+      # Called at the end of initialize so that subclass validates
+      # declarations are checked after setup_named_configurations.
+      # Errors with options[:type] == :warning are directed to config_warnings.
+      def run_validations
+        return if valid?
+
+        errors.each do |error|
+          level = error.options[:type] == :warning ? :warn : :error
+          failed_config error.attribute, "#{error.attribute} #{error.message}", level: level
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/batch_trigger.rb b/app/models/option_configs/extra_option_configs/batch_trigger.rb
new file mode 100644
index 0000000000..5cf7633c4a
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/batch_trigger.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for batch trigger setup.
+    # Uses the BaseConfiguration pattern with a single typed attribute
+    # `:on_record` that is a TriggerTasks instance.
+    #
+    # @example
+    #   bt = BatchTrigger.new(on_record: { notify: { type: 'email' } })
+    #   bt[:on_record]         #=> TriggerTasks instance
+    #   bt[:on_record].tasks   #=> { notify: { type: 'email' } }
+    class BatchTrigger < BaseConfiguration
+      configure_typed_attribute :on_record, type: TriggerTasks
+
+      # Set up typed attributes from the hash configuration.
+      # Delegates to OptionsHandler's setup_all_options_typed which
+      # instantiates TriggerTasks for the :on_record key.
+      # @return [void]
+      def setup_named_configurations
+        setup_all_options_typed(hash_configuration)
+        # Store the raw tasks value in configurations for hash-like access.
+        # Consumers expect raw Array/Hash, not TriggerTasks instance.
+        configurations[:on_record] = on_record.respond_to?(:tasks) ? on_record.tasks : on_record
+      end
+
+      # Returns true if there are no trigger tasks configured.
+      def blank?
+        on_record.blank?
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/caption_before.rb b/app/models/option_configs/extra_option_configs/caption_before.rb
new file mode 100644
index 0000000000..108fe34b25
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/caption_before.rb
@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for caption formatting (text-to-HTML conversion).
+    # Extracted from ExtraOptions#clean_caption_before_def
+    #
+    # Each field name maps to a NamedConfiguration with caption mode attributes.
+    # Preprocessing (string → hash expansion, text_to_html conversion) happens
+    # via add_named_configuration override.
+    class CaptionBefore < BaseConfiguration
+      # Named configuration for a single field's caption settings.
+      # Each field (e.g. :test1) has caption values for different display modes.
+      class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
+        configure_attributes %i[caption edit_caption show_caption new_caption]
+      end
+
+      # Override to preprocess caption values before creating NamedConfiguration.
+      # Handles string → hash expansion and text_to_html conversion.
+      def add_named_configuration(sym_key, value)
+        super(sym_key, preprocess_field(value))
+      end
+
+      private
+
+      # Pre-process a single field's raw value into a hash suitable for NamedConfiguration.
+      # - String values are expanded to all 4 caption mode keys with HTML conversion
+      # - Hash values have text_to_html applied to each mode value
+      # - new_caption defaults to edit_caption when not specified
+      # @param [String | Hash] value - raw caption value
+      # @return [Hash{Symbol => String}] processed hash with caption mode keys
+      def preprocess_field(value)
+        if value.is_a?(String)
+          html = Formatter::Substitution.text_to_html(value).strip
+          { caption: html, edit_caption: html, show_caption: html, new_caption: html }
+        elsif value.is_a?(Hash)
+          processed = {}
+          value.each { |mode, modeval| processed[mode.to_sym] = Formatter::Substitution.text_to_html(modeval).to_s.strip }
+          processed[:new_caption] = processed[:edit_caption] unless processed.key?(:new_caption)
+          processed
+        else
+          {}
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/config_base.rb b/app/models/option_configs/extra_option_configs/config_base.rb
new file mode 100644
index 0000000000..c83cba7bd7
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/config_base.rb
@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Base class for all ExtraOptions configuration classes.
+    # Each subclass encapsulates the normalization/cleaning logic
+    # for one top-level configuration area in ExtraOptions.
+    #
+    # Subclasses should:
+    # - Declare managed attributes with `attribute :name`
+    # - Implement `#clean` to normalize values
+    # - Use `#failed_config` to report configuration errors
+    #
+    # @example
+    #   class LabelDef < ConfigBase
+    #     attribute :label
+    #
+    #     def clean
+    #       self.label = parent_options.label || parent_options.name.to_s.humanize
+    #     end
+    #   end
+    class ConfigBase
+      include ActiveModel::Validations
+
+      attr_reader :parent_options
+
+      # Track which attributes this config class manages
+      # Each subclass maintains its own list via Ruby class instance variables
+      # @return [Array<Symbol>]
+      def self.managed_attributes
+        @managed_attributes ||= []
+      end
+
+      # Declare one or more managed attributes on this config class.
+      # Creates attr_accessor and registers the attribute names.
+      # @param names [Array<Symbol>] attribute names
+      def self.attribute(*names)
+        attr_accessor(*names)
+
+        managed_attributes.push(*names)
+      end
+
+      # Declare that this class stores a single direct value of a given type.
+      # Records type metadata in option_types[:direct] for reflection.
+      # @param config_item_name [Symbol] the attribute name
+      # @param type [Symbol] the value type (:string, :array, :hash, :if_condition)
+      def self.configure_direct(config_item_name, type:)
+        attribute(config_item_name) unless managed_attributes.include?(config_item_name)
+
+        option_types[:direct] << config_item_name
+
+        @direct_types ||= {}
+        @direct_types[config_item_name] = type
+      end
+
+      # Returns the option types declared on this class.
+      # @return [Hash{Symbol => Array<Symbol>}]
+      def self.option_types
+        @option_types ||= { direct: [] }
+      end
+
+      # Returns the registered direct types for this class.
+      # @return [Hash{Symbol => Symbol}]
+      def self.direct_types
+        @direct_types || {}
+      end
+
+      # @param parent_options [OptionConfigs::ExtraOptions] the parent ExtraOptions instance
+      def initialize(parent_options)
+        @parent_options = parent_options
+        clean
+      end
+
+      # Write cleaned attribute values back to the parent ExtraOptions instance.
+      # Called after #clean to synchronize values.
+      def apply_to_parent!
+        self.class.managed_attributes.each do |attr|
+          parent_options.send("#{attr}=", send(attr))
+        end
+      end
+
+      # Override in subclasses to perform cleaning/normalization
+      # @raise [NotImplementedError] if not overridden
+      def clean
+        raise NotImplementedError, "#{self.class.name} must implement #clean"
+      end
+
+      private
+
+      # Access the dynamic definition record (DynamicModel, ActivityLog, etc.)
+      # @return [ActiveRecord::Base]
+      def config_obj
+        parent_options.config_obj
+      end
+
+      # Delegate error reporting to the parent ExtraOptions instance
+      # @param type [Symbol] error category
+      # @param message [String] error message
+      # @param extra_details [Object] additional detail
+      # @param level [Symbol] :error or :warn
+      def failed_config(type, message, extra_details: nil, level: :error)
+        parent_options.send(:failed_config, type, message, extra_details:, level:)
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/config_trigger.rb b/app/models/option_configs/extra_option_configs/config_trigger.rb
new file mode 100644
index 0000000000..a38cb66115
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/config_trigger.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for config trigger setup.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Uses a typed TriggerTasks attribute for on_define.
+    #
+    # Handles:
+    # - Wrapping a single on_define hash in an array
+    # - Defaulting on_define to an empty TriggerTasks when not provided
+    #
+    # @example
+    #   ct = ConfigTrigger.new(on_define: [{ action: 'do_something' }])
+    #   ct.on_define.tasks #=> [{ action: 'do_something' }]
+    class ConfigTrigger < BaseConfiguration
+      configure_typed_attribute :on_define, type: TriggerTasks
+
+      # Preprocess on_define (wrap non-array in array, default to empty)
+      # then delegate to typed attribute initialization.
+      # @return [void]
+      def setup_named_configurations
+        od = hash_configuration[:on_define]
+        od = [od] if od.is_a?(Hash)
+        hash_configuration[:on_define] = od || []
+
+        setup_all_options_typed(hash_configuration)
+
+        # Store raw tasks values in configurations for hash-like bracket access.
+        # Consumers expect raw Array/Hash, not TriggerTasks instances.
+        self.class.option_types[:typed].each do |key|
+          typed = send(key)
+          configurations[key] = typed.respond_to?(:tasks) ? typed.tasks : typed
+        end
+      end
+
+      # Returns true when on_define has no tasks.
+      def blank?
+        on_define.blank?
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/creatable_if.rb b/app/models/option_configs/extra_option_configs/creatable_if.rb
new file mode 100644
index 0000000000..83d8ee9b77
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/creatable_if.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for creatable_if access control condition.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Split from AccessIf to manage a single if_condition directly.
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class CreatableIf < BaseConfiguration
+      configure_direct :creatable_if, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Store the symbolized hash value, defaulting to empty hash.
+      # Populate configurations for hash-like bracket access.
+      # @return [void]
+      def setup_named_configurations
+        self.creatable_if = hash_configuration.presence || {}
+        creatable_if.each { |k, v| configurations[k] = v }
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/db_configs.rb b/app/models/option_configs/extra_option_configs/db_configs.rb
new file mode 100644
index 0000000000..1ef9a50873
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/db_configs.rb
@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for database column configs.
+    # Extracted from ExtraOptions#clean_db_configs_def
+    #
+    # Values are column configuration hashes keyed by column name.
+    # The mutation of config_obj.db_columns is handled by ExtraOptions
+    # after this config class runs.
+    class DbConfigs < BaseConfiguration
+      # No special processing needed — keys are already symbolized
+      # by parse_options_text's deep_symbolize_keys!
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/dialog_before.rb b/app/models/option_configs/extra_option_configs/dialog_before.rb
new file mode 100644
index 0000000000..58fba8b839
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/dialog_before.rb
@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for dialog overlay definitions.
+    # Extracted from ExtraOptions#clean_dialog_before_def
+    #
+    # Each field name maps to a NamedConfiguration with dialog attributes.
+    # String values are expanded to { name: string } hashes.
+    # Validates that referenced Admin::MessageTemplate records exist.
+    class DialogBefore < BaseConfiguration
+      # Named configuration for a single field's dialog settings.
+      class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
+        configure_attributes %i[name label keep_label]
+      end
+
+      validate :validate_dialog_entries
+
+      # Override to preprocess and validate dialog values.
+      # Converts strings to { name: string } hashes, validates template existence.
+      def add_named_configuration(sym_key, value)
+        processed = preprocess_field(sym_key, value)
+        return unless processed
+
+        super(sym_key, processed)
+      end
+
+      private
+
+      # Pre-process a single dialog_before value.
+      # @param [Symbol] key - field name (used in error messages)
+      # @param [String | Hash] value - raw dialog value
+      # @return [Hash | nil] processed hash, or nil if invalid
+      def preprocess_field(key, value)
+        if value.is_a?(String)
+          { name: value }
+        elsif value.is_a?(Hash)
+          value.symbolize_keys
+        else
+          nil
+        end
+      end
+
+      # Validate dialog_before entries via ActiveModel validate callback.
+      # Checks for invalid types and missing message templates.
+      def validate_dialog_entries
+        return if hash_configuration.blank?
+
+        hash_configuration.each do |key, value|
+          unless value.is_a?(String) || value.is_a?(Hash)
+            errors.add(:dialog_before,
+                       "must be a Hash { name: '<template name>' } or String: #{key}")
+            next
+          end
+
+          processed = value.is_a?(String) ? { name: value } : value.symbolize_keys
+          name = processed[:name]
+          next unless name
+
+          mt = Admin::MessageTemplate.active.find_by(name:)
+          next if mt
+
+          errors.add(:dialog_before,
+                     "specifies a named message template that doesn't exist: #{name}",
+                     type: :warning)
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/e_sign_config.rb b/app/models/option_configs/extra_option_configs/e_sign_config.rb
new file mode 100644
index 0000000000..67a7ecc14c
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/e_sign_config.rb
@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for e-signature definitions.
+    # Migrated from ActivityLogOptions#clean_e_sign_def (issue #986).
+    #
+    # Transforms e_sign document_reference structure: wraps in {item: ...},
+    # singularizes keys, and resolves model references.
+    #
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class ESignConfig < BaseConfiguration
+      configure_direct :e_sign, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Pre-process the e_sign config: wrap document_reference, singularize keys,
+      # and resolve model references.
+      # @param raw [Hash, nil] the raw e_sign config
+      # @param _parent [ExtraOptions] the parent ExtraOptions instance (unused)
+      # @return [Hash, nil] the processed e_sign hash
+      def self.prepare_config(raw, _parent)
+        return nil unless raw
+
+        raw = raw.symbolize_keys if raw.is_a?(Hash)
+
+        # Wrap document_reference in {item: ...} if not already wrapped
+        raw[:document_reference] = { item: raw[:document_reference] } unless raw[:document_reference][:item]
+
+        raw[:document_reference].each_value do |refitem|
+          # Singularize all keys
+          refitem.transform_keys! do |k|
+            k.to_s.singularize.to_sym
+          end
+
+          refitem.each do |mn, conf|
+            to_class = ModelReference.to_record_class_for_type(mn)
+
+            refitem[mn][:to_record_label] = conf[:label] || to_class&.human_name
+            if to_class&.respond_to?(:no_master_association)
+              refitem[mn][:no_master_association] = to_class.no_master_association
+            end
+            refitem[mn][:to_model_name_us] = to_class&.to_s&.ns_underscore
+          end
+        end
+
+        raw
+      end
+
+      def setup_named_configurations
+        self.e_sign = hash_configuration
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/editable_if.rb b/app/models/option_configs/extra_option_configs/editable_if.rb
new file mode 100644
index 0000000000..7db9c2ce69
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/editable_if.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for editable_if access control condition.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Split from AccessIf to manage a single if_condition directly.
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class EditableIf < BaseConfiguration
+      configure_direct :editable_if, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Store the symbolized hash value, defaulting to empty hash.
+      # Populate configurations for hash-like bracket access.
+      # @return [void]
+      def setup_named_configurations
+        self.editable_if = hash_configuration.presence || {}
+        editable_if.each { |k, v| configurations[k] = v }
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/embed.rb b/app/models/option_configs/extra_option_configs/embed.rb
new file mode 100644
index 0000000000..165b9292d8
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/embed.rb
@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for embedded resource definitions.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    #
+    # Handles:
+    # - Converting 'default_embed_resource' string to resource_name hash
+    # - Converting plain string to { resource_name: string } hash
+    # - Looking up the resource model definition
+    # - Warning when embedded resource does not exist
+    #
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class Embed < BaseConfiguration
+      configure_direct :embed, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      validate :validate_embed_resource
+
+      # Pre-process the embed value using parent context.
+      # Converts string values and 'default_embed_resource' to hash format.
+      # Looks up the resource model and reports warnings for missing resources.
+      # @param raw [String, Hash, nil] the raw embed value from YAML config
+      # @param parent [ExtraOptions] the parent ExtraOptions instance
+      # @return [Hash, nil] the processed embed hash
+      def self.prepare_config(raw, parent)
+        return nil unless raw
+
+        config_obj = parent.config_obj
+
+        if raw == 'default_embed_resource'
+          rn = config_obj.default_embed_resource_name(parent.name)
+          emb = { resource_name: rn }
+        elsif raw.is_a?(String)
+          rn = raw
+          emb = { resource_name: rn }
+        else
+          emb = raw.is_a?(Hash) ? raw.symbolize_keys : {}
+          rn = emb[:resource_name]
+        end
+
+        resource = Resources::Models.find_by(resource_name: rn)
+        emb[:resource_model_def] = resource
+
+        unless resource && resource[:model]
+          Rails.logger.warn "embed for #{rn} does not exist as a class in #{parent.name} / #{config_obj.name}"
+        end
+
+        emb
+      end
+
+      # Store the embed hash value.
+      # Handles string input by converting to resource_name hash.
+      # @return [void]
+      def setup_named_configurations
+        raw = hash_configuration
+        self.embed = if raw.is_a?(String)
+                       { resource_name: raw }
+                     elsif raw.is_a?(Hash) && raw.present?
+                       raw
+                     else
+                       raw.presence
+                     end
+      end
+
+      private
+
+      # Validate that the embedded resource exists.
+      def validate_embed_resource
+        emb = hash_configuration
+        return if emb.blank? || !emb.is_a?(Hash)
+
+        rn = emb[:resource_name]
+        return unless rn
+
+        resource = emb[:resource_model_def]
+        return if resource && resource[:model]
+
+        errors.add(:embed, "embed for #{rn} does not exist as a resource", type: :warning)
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/field_configs.rb b/app/models/option_configs/extra_option_configs/field_configs.rb
new file mode 100644
index 0000000000..0256f570b8
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/field_configs.rb
@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for per-field configuration merging.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    #
+    # Handles:
+    # - Parsing field_configs and distributing values to standalone config attributes
+    # - Validating field_configs fields are in the field list
+    # - Validating field_configs keys are in ValidFieldConfigs
+    # - Merging standalone definitions back into field_configs
+    #
+    # Note: This config class reads from and writes to multiple parent attributes
+    # (field_configs, plus the ValidFieldConfigs attributes like caption_before, labels, etc.)
+    # because the clean_field_configs method has cross-cutting behavior.
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class FieldConfigs < BaseConfiguration
+      configure_direct :field_configs, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Pre-process field_configs using parent context.
+      # Distributes field config values to standalone parent attributes and validates.
+      # @param raw [Hash, nil] the raw field_configs value from YAML config
+      # @param parent [ExtraOptions] the parent ExtraOptions instance
+      # @return [Hash] the processed field_configs hash
+      def self.prepare_config(raw, parent)
+        # Fields is already processed at this point (it runs before FieldConfigs in the registry)
+        fla = parent.fields || []
+
+        return {} if raw.nil?
+
+        fc = raw.symbolize_keys
+        failed = false
+        validation_errors = []
+        fc.each do |fname, fconfig|
+          unless fconfig&.is_a? Hash
+            validation_errors << "field '#{fname}' is not a Hash"
+            failed = true
+            fc[fname] = {}
+            next
+          end
+
+          OptionConfigs::ExtraOptions::ValidFieldConfigs.each do |vc|
+            c = fconfig[vc]
+            next unless c
+
+            ivar = parent.instance_variable_get("@#{vc}")
+            unless ivar
+              parent.instance_variable_set("@#{vc}", {})
+              ivar = parent.instance_variable_get("@#{vc}")
+            end
+
+            ivar.merge!(fname => c)
+          end
+        end
+
+        if failed
+          fc[:_validation_errors] = validation_errors if validation_errors.present?
+          return fc
+        end
+
+        # Build the list of errors from the explicitly defined field_configs
+        efs = fc.keys.map(&:to_s) - fla
+        if efs.present?
+          validation_errors << "field_configs includes fields that are not in the field list: #{efs.join(', ')}"
+        end
+
+        fc.each do |fname, fconfig|
+          extra_keys = fconfig.keys - OptionConfigs::ExtraOptions::ValidFieldConfigs
+          next if extra_keys.empty?
+
+          validation_errors << "field_configs for #{fname} includes invalid keys: #{extra_keys}"
+        end
+
+        # Merge raw standalone definitions into field_configs BEFORE standalone classes clean them.
+        # This matches the old clean_field_configs behavior where add_field_configs_from_standalone_defs
+        # was called internally, producing raw_field_configs with uncleaned values.
+        OptionConfigs::ExtraOptions::ValidFieldConfigs.each do |vc|
+          c = parent.instance_variable_get("@#{vc}")
+          next unless c
+
+          c_hash = c.is_a?(Hash) ? c.symbolize_keys : next
+          c_hash.each do |k, v|
+            next unless fla.include?(k.to_s)
+
+            fc[k] ||= {}
+            fc[k].merge!({ vc => v })
+          end
+        end
+
+        # Save pre-clean snapshot for raw_field_configs
+        # Using Marshal for deep cloning is safe here since we're only operating on data already in memory
+        parent.raw_field_configs = Marshal.load(Marshal.dump(fc))
+
+        fc[:_validation_errors] = validation_errors if validation_errors.present?
+
+        fc
+      end
+
+      validate :validate_field_configs
+
+      # Store the field_configs hash value, defaulting to empty hash.
+      # @return [void]
+      def setup_named_configurations
+        self.field_configs = hash_configuration.except(:_validation_errors).presence || {}
+      end
+
+      private
+
+      # Validate field_configs entries via ActiveModel validate callback.
+      def validate_field_configs
+        stored_errors = hash_configuration[:_validation_errors]
+        return unless stored_errors&.present?
+
+        stored_errors.each do |msg|
+          errors.add(:field_configs, msg)
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/field_options.rb b/app/models/option_configs/extra_option_configs/field_options.rb
new file mode 100644
index 0000000000..568f83851f
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/field_options.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for field-level edit options.
+    # Extracted from ExtraOptions#clean_field_options_def
+    #
+    # Values are arbitrary option hashes keyed by field name.
+    # Handles converting edit_as.alt_options from Array to Hash.
+    class FieldOptions < BaseConfiguration
+      # No NamedConfiguration — values are arbitrary option hashes
+
+      # Override to preprocess alt_options arrays.
+      def add_named_configuration(sym_key, value)
+        super(sym_key, preprocess_field(value))
+      end
+
+      private
+
+      # Convert edit_as.alt_options from Array to Hash if needed.
+      # @param [Object] value - raw field option value
+      # @return [Object] processed value
+      def preprocess_field(value)
+        return value unless value.is_a?(Hash)
+
+        ao = value.dig(:edit_as, :alt_options)
+        return value unless ao.is_a?(Array)
+
+        new_ao = {}
+        ao.each { |aov| new_ao[aov.to_s.to_sym] = aov.to_s.downcase }
+        value[:edit_as][:alt_options] = new_ao
+        value
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/fields.rb b/app/models/option_configs/extra_option_configs/fields.rb
new file mode 100644
index 0000000000..67302b0069
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/fields.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for field list setup.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the field list as a direct array value.
+    # The processed array is stored back on the parent ExtraOptions (not the object).
+    class Fields < BaseConfiguration
+      configure_direct :fields, type: :array
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Store the array value, defaulting to empty array.
+      # @return [void]
+      def setup_named_configurations
+        self.fields = hash_configuration.is_a?(Array) ? hash_configuration : []
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/filestore.rb b/app/models/option_configs/extra_option_configs/filestore.rb
new file mode 100644
index 0000000000..f3f7ea6af2
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/filestore.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for filestore configuration.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the entire hash as a single direct attribute.
+    #
+    # @example
+    #   fs = Filestore.new(container: { path: '/data' })
+    #   fs.filestore #=> { container: { path: '/data' } }
+    class Filestore < BaseConfiguration
+      configure_direct :filestore, type: :hash
+
+      # Store the entire input hash as the filestore attribute
+      # and populate configurations for hash-like [] access.
+      # @return [void]
+      def setup_named_configurations
+        self.filestore = hash_configuration.presence || {}
+        filestore.each { |k, v| configurations[k] = v }
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/if_condition.rb b/app/models/option_configs/extra_option_configs/if_condition.rb
new file mode 100644
index 0000000000..13109032cd
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/if_condition.rb
@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Reusable configuration class for if_condition hashes
+    # (e.g. creatable_if, editable_if, showable_if conditions).
+    #
+    # Stores the entire conditions hash as a single attribute rather than
+    # splitting it into individual field-keyed entries.
+    #
+    # @example
+    #   cond = IfCondition.new(always: true, user_is_creator: true)
+    #   cond.conditions  #=> { always: true, user_is_creator: true }
+    #   cond.blank?      #=> false
+    class IfCondition < BaseConfiguration
+      configure_direct :conditions, type: :hash
+
+      # Override default field-keyed setup to store the hash as a single value
+      # on the conditions attribute.
+      # @return [void]
+      def setup_named_configurations
+        self.conditions = (hash_configuration || {}).symbolize_keys
+      end
+
+      # Returns true when no conditions are defined.
+      def blank?
+        conditions.blank?
+      end
+
+      # Returns the conditions hash for backward compatibility.
+      # @return [Hash{Symbol => Object}]
+      def symbolize_keys
+        conditions || {}
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/label.rb b/app/models/option_configs/extra_option_configs/label.rb
new file mode 100644
index 0000000000..e508442bb6
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/label.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for the definition label.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the label string as a direct value.
+    # Uses prepare_config to default to humanized name when not specified.
+    # The processed string is stored back on the parent ExtraOptions (not the object).
+    class Label < BaseConfiguration
+      configure_direct :label, type: :string
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Default the label to the humanized option name when not specified.
+      # @param raw [String, nil] the raw label value from YAML config
+      # @param parent [ExtraOptions] the parent ExtraOptions instance
+      # @return [String] the label string
+      def self.prepare_config(raw, parent)
+        raw || parent.name.to_s.humanize
+      end
+
+      # Store the string value, defaulting to empty string.
+      # @return [void]
+      def setup_named_configurations
+        self.label = hash_configuration.is_a?(String) ? hash_configuration : ''
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/labels.rb b/app/models/option_configs/extra_option_configs/labels.rb
new file mode 100644
index 0000000000..bb5fa28487
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/labels.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for field labels.
+    # Extracted from ExtraOptions#clean_labels_def
+    #
+    # Values are plain strings keyed by field name.
+    # No NamedConfiguration needed — values are simple strings.
+    class Labels < BaseConfiguration
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/nfs_store_config.rb b/app/models/option_configs/extra_option_configs/nfs_store_config.rb
new file mode 100644
index 0000000000..4b37748459
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/nfs_store_config.rb
@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for NFS store definitions.
+    # Migrated from ActivityLogOptions#clean_nfs_store_def (issue #986).
+    #
+    # Validates nfs_store top-level and can sub-keys, and delegates
+    # pipeline cleaning to NfsStore::Config::ExtraOptions.clean_def.
+    #
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class NfsStoreConfig < BaseConfiguration
+      configure_direct :nfs_store, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      validate :validate_nfs_store_keys
+
+      # Delegate pipeline cleaning to NfsStore::Config::ExtraOptions.
+      # @param raw [Hash, nil] the raw nfs_store config
+      # @param _parent [ExtraOptions] the parent ExtraOptions instance (unused)
+      # @return [Hash, nil] the raw config after pipeline cleaning
+      def self.prepare_config(raw, _parent)
+        return nil unless raw
+
+        NfsStore::Config::ExtraOptions.clean_def(raw)
+        raw
+      end
+
+      def setup_named_configurations
+        self.nfs_store = hash_configuration
+      end
+
+      private
+
+      def validate_nfs_store_keys
+        raw = hash_configuration
+        return if raw.blank?
+
+        unless valid_nfs_store_top_keys?(raw)
+          errors.add(:nfs_store,
+                     "nfs_store contains invalid keys #{raw.keys} - " \
+                     "expected only #{ActivityLogOptions::ValidNfsStoreKeys}")
+        end
+
+        can_perform = raw[:can]
+        return if can_perform.nil?
+
+        return if valid_nfs_store_can_keys?(can_perform)
+
+        errors.add(:nfs_store,
+                   "nfs_store.can contains invalid keys #{can_perform.keys} - " \
+                   "expected only #{ActivityLogOptions::ValidNfsStoreCanPerformKeys}")
+      end
+
+      def valid_nfs_store_top_keys?(config)
+        config.keys.empty? || (config.keys - ActivityLogOptions::ValidNfsStoreKeys).empty?
+      end
+
+      def valid_nfs_store_can_keys?(config)
+        config.keys.empty? || (config.keys - ActivityLogOptions::ValidNfsStoreCanPerformKeys).empty?
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/preset_fields.rb b/app/models/option_configs/extra_option_configs/preset_fields.rb
new file mode 100644
index 0000000000..88ede85787
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/preset_fields.rb
@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for preset field values.
+    # Extracted from ExtraOptions#clean_preset_fields
+    #
+    # Values are preset values (strings, hashes, or arrays) keyed by field name.
+    class PresetFields < BaseConfiguration
+      # No special processing needed — values stored directly
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/references.rb b/app/models/option_configs/extra_option_configs/references.rb
new file mode 100644
index 0000000000..fe04b3a7ce
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/references.rb
@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for model reference configurations.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    #
+    # Handles:
+    # - Converting array-style and hash-style references
+    # - Singularizing reference keys
+    # - Looking up target classes and enriching reference metadata
+    # - Warning when referenced models do not exist
+    #
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class References < BaseConfiguration
+      configure_direct :references, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      validate :validate_references
+
+      # Pre-process references using parent context.
+      # Converts array/hash formats, singularizes keys, looks up target classes.
+      # @param raw [Array, Hash, nil] the raw references value from YAML config
+      # @param parent [ExtraOptions] the parent ExtraOptions instance
+      # @return [Hash, nil] the processed references hash
+      def self.prepare_config(raw, parent)
+        return nil unless raw
+
+        config_obj = parent.config_obj
+        new_ref = {}
+
+        if raw.is_a? Array
+          raw.each do |refitem|
+            # Make all keys singular, to simplify configurations
+            add_refitem = {}
+            refitem.each do |k, _v|
+              if k.to_s != k.to_s.singularize
+                new_k = k.to_s.singularize.to_sym
+                add_refitem[new_k] = refitem.delete(k)
+              end
+            end
+
+            refitem.merge! add_refitem
+
+            refitem.each do |k, v|
+              vi = v[:add_with] && v[:add_with][:extra_log_type]
+              ckey = k.to_s
+              ckey += "_#{vi}" if vi
+              new_ref[ckey.to_sym] = { k => v }
+            end
+          end
+        else
+          refs = raw.dup
+          fix_refs = {}
+
+          # Make all keys singular, to simplify configurations
+          refs.each do |k, _v|
+            fix_refs[k] = refs[k] if k.to_s != k.to_s.singularize
+          end
+
+          fix_refs.each do |k, _v|
+            new_k = k.to_s.singularize.to_sym
+            refs[new_k] = refs.delete(k)
+          end
+
+          refs.each do |k, v|
+            vi = v[:add_with] && v[:add_with][:extra_log_type]
+            ckey = k.to_s
+            ckey += "_#{vi}" if vi
+            new_ref[ckey.to_sym] = { k => v }
+          end
+        end
+
+        all_bad_items = []
+        bad_items = []
+        new_ref.each do |_k, refitem|
+          bad_items.clear
+          refitem.each do |mn, conf|
+            to_class = ModelReference.to_record_class_for_type(mn)
+
+            # Avoid breaking app type imports if the resource being pointed to in the reference
+            # hasn't been set up yet.
+            if to_class.nil? || (to_class.respond_to?(:definition) && !to_class.definition)
+              Rails.logger.warn "Definition for class #{to_class} is not set - skipping reference setup for #{mn}"
+              all_bad_items << mn
+              bad_items << mn
+              break
+            end
+
+            if to_class
+              elt = conf[:add_with] && conf[:add_with][:extra_log_type]
+              add_with_elt = nil
+              add_with_elt = to_class.human_name_for(elt) if elt && to_class.respond_to?(:human_name_for)
+              refitem[mn][:to_record_label] = conf[:result_label] || conf[:label] || add_with_elt || to_class.human_name
+
+              if to_class.respond_to?(:no_master_association)
+                refitem[mn][:no_master_association] = to_class.no_master_association
+              end
+
+              refitem[mn][:to_model_name_us] = to_class.to_s&.ns_underscore
+              refitem[mn][:to_model_class_name] = to_class.to_s
+              refitem[mn][:to_table_name] = to_class.table_name
+              nil
+
+              if to_class.respond_to?(:definition)
+                cd = to_class.definition
+                tsn = cd.schema_name
+                tct = cd.class.to_s
+                refitem[mn][:to_schema_name] = tsn
+                refitem[mn][:to_class_type] = tct
+              end
+            else
+              bad_items << mn
+              all_bad_items << mn
+              Rails.logger.warn "extra log type reference for #{mn} does not exist as a class in #{parent.name} / #{config_obj.name}"
+              Rails.logger.info 'Will clean up reference to avoid it being used again in this session'
+            end
+          end
+
+          # Cleanup bad items
+          bad_items.each do |br|
+            refitem.delete(br)
+          end
+        end
+
+        # Store bad_ref_items on parent for backward compatibility
+        parent.bad_ref_items = bad_items
+
+        new_ref[:_bad_references] = all_bad_items if all_bad_items.present?
+
+        new_ref
+      end
+
+      # Re-process references on an already-initialized ExtraOptions instance.
+      # Use this after mutating `instance.references` post-initialization.
+      # @param instance [ExtraOptions] the ExtraOptions instance to reprocess
+      # @return [void]
+      def self.reprocess(instance)
+        instance.references = prepare_config(instance.references, instance)
+      end
+
+      # Store the references hash value.
+      # @return [void]
+      def setup_named_configurations
+        self.references = hash_configuration.except(:_bad_references).presence
+      end
+
+      private
+
+      # Validate that all referenced models exist.
+      def validate_references
+        bad_refs = hash_configuration[:_bad_references]
+        return unless bad_refs&.present?
+
+        bad_refs.each do |mn|
+          errors.add(:references, "reference for #{mn} does not exist as a class", type: :warning)
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/save_action.rb b/app/models/option_configs/extra_option_configs/save_action.rb
new file mode 100644
index 0000000000..1ec3b05938
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/save_action.rb
@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for save action cascading (on_save -> on_create/on_update).
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the entire hash as a single direct attribute after cascading.
+    #
+    # Handles:
+    # - on_save cascade to on_create and on_update (hash merge)
+    #
+    # @example
+    #   sa = SaveAction.new(on_save: { label: 'Saved' })
+    #   sa.save_action[:on_create] #=> { label: 'Saved' }
+    class SaveAction < BaseConfiguration
+      configure_direct :save_action, type: :hash
+
+      # Store the input hash with on_save cascade applied
+      # and populate configurations for hash-like [] access.
+      # @return [void]
+      def setup_named_configurations
+        sa = hash_configuration.presence || {}
+        cascade_on_save(sa)
+        self.save_action = sa
+        sa.each { |k, v| configurations[k] = v }
+      end
+
+      private
+
+      # Cascade on_save into on_create and on_update as defaults.
+      # on_save values are merged as base, with specific key values taking priority.
+      # @param [Hash] sa - the save_action hash (modified in place)
+      # @return [void]
+      def cascade_on_save(sa)
+        os = sa[:on_save]
+        return unless os
+
+        ou = sa[:on_update] || {}
+        oc = sa[:on_create] || {}
+        sa[:on_update] = os.merge(ou)
+        sa[:on_create] = os.merge(oc)
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/save_trigger.rb b/app/models/option_configs/extra_option_configs/save_trigger.rb
new file mode 100644
index 0000000000..5eac06058a
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/save_trigger.rb
@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for save trigger cascading.
+    # Uses the BaseConfiguration pattern with typed attributes for each
+    # trigger key, all typed as TriggerTasks.
+    #
+    # Handles:
+    # - Key validation against ValidSaveTriggerTriggers
+    # - on_save cascade to on_create/on_update (wrapping hashes into arrays)
+    # - Default blank TriggerTasks for on_upload and on_disable
+    #
+    # @example
+    #   st = SaveTrigger.new(on_save: { notify: { type: 'email' } })
+    #   st[:on_create].tasks  #=> [{ notify: { type: 'email' } }]
+    class SaveTrigger < BaseConfiguration
+      configure_typed_attribute :on_create, type: TriggerTasks
+      configure_typed_attribute :on_update, type: TriggerTasks
+      configure_typed_attribute :on_save, type: TriggerTasks
+      configure_typed_attribute :on_upload, type: TriggerTasks
+      configure_typed_attribute :on_disable, type: TriggerTasks
+      configure_typed_attribute :before_save, type: TriggerTasks
+
+      validate :validate_keys
+
+      # Set up typed attributes with cascade logic.
+      # @return [void]
+      def setup_named_configurations
+        cascade_on_save
+
+        setup_all_options_typed(hash_configuration)
+
+        # Store the raw tasks values in configurations for hash-like bracket access.
+        # Consumers expect raw Array/Hash, not TriggerTasks instances.
+        self.class.option_types[:typed].each do |key|
+          typed = send(key)
+          configurations[key] = typed.respond_to?(:tasks) ? typed.tasks : typed
+        end
+      end
+
+      # Returns true if no trigger tasks are configured on any key.
+      def blank?
+        self.class.option_types[:typed].all? { |key| send(key).blank? }
+      end
+
+      private
+
+      # Validate keys against the allowed set.
+      # @return [void]
+      def validate_keys
+        return unless hash_configuration.is_a?(Hash)
+        return if hash_configuration.keys.empty?
+
+        invalid = hash_configuration.keys - OptionConfigs::ExtraOptions::ValidSaveTriggerTriggers
+        return if invalid.empty?
+
+        errors.add(:save_trigger,
+                   "contains invalid keys #{hash_configuration.keys} - expected only: #{OptionConfigs::ExtraOptions::ValidSaveTriggerTriggers}")
+      end
+
+      # Cascade on_save into on_create and on_update (wrapping hashes into arrays).
+      # Modifies hash_configuration in place before typed attributes are initialized.
+      # @return [void]
+      def cascade_on_save
+        return unless hash_configuration.is_a?(Hash)
+
+        os = hash_configuration[:on_save]
+        return unless os
+
+        os = [os] if os.is_a?(Hash)
+
+        oc = hash_configuration[:on_create]
+        ou = hash_configuration[:on_update]
+        oc = [oc] if oc.is_a?(Hash)
+        ou = [ou] if ou.is_a?(Hash)
+        oc ||= []
+        ou ||= []
+
+        hash_configuration[:on_create] = os + oc
+        hash_configuration[:on_update] = os + ou
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/set_variable.rb b/app/models/option_configs/extra_option_configs/set_variable.rb
new file mode 100644
index 0000000000..2fd7eaae0a
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/set_variable.rb
@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for variable definitions.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the validated array as a direct attribute.
+    #
+    # Handles:
+    # - Validating set_variables is an array
+    # - Validating each entry has :name and :value keys
+    # - Filtering out invalid entries
+    #
+    # @example
+    #   sv = SetVariable.new([{ name: 'var1', value: 'val1' }])
+    #   sv.set_variables #=> [{ name: 'var1', value: 'val1' }]
+    class SetVariable < BaseConfiguration
+      configure_direct :set_variables, type: :array
+
+      validate :validate_structure
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Parse and store the input array.
+      # @return [void]
+      def setup_named_configurations
+        raw = hash_configuration
+        if raw.blank?
+          self.set_variables = nil
+          return
+        end
+
+        unless raw.is_a?(Array)
+          self.set_variables = []
+          return
+        end
+
+        self.set_variables = raw.filter_map do |entry|
+          entry = entry.symbolize_keys if entry.is_a?(Hash)
+          next nil unless entry.is_a?(Hash) && entry[:name].present? && entry.key?(:value)
+
+          entry
+        end
+      end
+
+      # Returns true when no variables are defined.
+      def blank?
+        set_variables.blank?
+      end
+
+      private
+
+      # Validate set_variables structure.
+      # @return [void]
+      def validate_structure
+        raw = hash_configuration
+        return if raw.blank?
+
+        unless raw.is_a?(Array)
+          errors.add(:set_variables, 'must be an array of variable definitions')
+          return
+        end
+
+        raw.each do |entry|
+          entry = entry.symbolize_keys if entry.is_a?(Hash)
+          next if entry.is_a?(Hash) && entry[:name].present? && entry.key?(:value)
+
+          errors.add(:set_variables, "each entry must have 'name' and 'value' keys")
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/show_if.rb b/app/models/option_configs/extra_option_configs/show_if.rb
new file mode 100644
index 0000000000..4056f0ff7e
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/show_if.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for conditional visibility (show_if).
+    # Extracted from ExtraOptions#clean_show_if_def
+    #
+    # Values are arbitrary condition hashes keyed by field name.
+    # show_if_condition_strings (REDCap branching logic) are preprocessed
+    # via prepare_config before initialization.
+    class ShowIf < BaseConfiguration
+      # No NamedConfiguration — values are arbitrary condition hashes
+
+      # Pre-process config using parent context to merge
+      # show_if_condition_strings (REDCap branching logic).
+      # Called by ExtraOptions before initialization.
+      # @param [Hash] raw - raw show_if hash from YAML
+      # @param [ExtraOptions] parent - parent ExtraOptions instance
+      # @return [Hash] merged show_if hash
+      def self.prepare_config(raw, parent)
+        raw ||= {}
+
+        parent.show_if_condition_strings&.each do |fn, val|
+          next if val.nil? || val.empty? || raw[fn]
+
+          begin
+            bl = Redcap::DataDictionaries::BranchingLogic.new(val)
+            sis = bl&.generate_show_if
+            raw[fn] = sis if sis.present?
+          rescue StandardError => e
+            Rails.logger.warn "Failed to generate real show_if (in #{parent.config_obj&.resource_name}) " \
+                              "for #{fn}: #{val}\n#{e}"
+            raw[fn] = { generate_show_if: "failed - #{e}" }
+          end
+        end
+
+        raw
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/showable_if.rb b/app/models/option_configs/extra_option_configs/showable_if.rb
new file mode 100644
index 0000000000..4eb9377ecf
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/showable_if.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for showable_if access control condition.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Split from AccessIf to manage a single if_condition directly.
+    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    class ShowableIf < BaseConfiguration
+      configure_direct :showable_if, type: :hash
+
+      def self.store_processed_value?
+        true
+      end
+
+      # Store the symbolized hash value, defaulting to empty hash.
+      # Populate configurations for hash-like bracket access.
+      # @return [void]
+      def setup_named_configurations
+        self.showable_if = hash_configuration.presence || {}
+        showable_if.each { |k, v| configurations[k] = v }
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/trigger_tasks.rb b/app/models/option_configs/extra_option_configs/trigger_tasks.rb
new file mode 100644
index 0000000000..456bc7d3f9
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/trigger_tasks.rb
@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Reusable configuration class for trigger task hashes or arrays.
+    # Used by BatchTrigger (on_record), SaveTrigger (on_create, on_update, etc.)
+    # to store trigger task configurations.
+    #
+    # Accepts either a Hash or an Array of trigger task hashes.
+    # Hash values get symbolized keys; arrays are stored as-is.
+    #
+    # @example Hash input
+    #   tasks = TriggerTasks.new(notify: { type: 'email' }, update_this: { field: 'val' })
+    #   tasks.tasks  #=> { notify: { type: 'email' }, update_this: { field: 'val' } }
+    #
+    # @example Array input
+    #   tasks = TriggerTasks.new([{ notify: { type: 'email' } }])
+    #   tasks.tasks  #=> [{ notify: { type: 'email' } }]
+    class TriggerTasks < BaseConfiguration
+      configure_direct :tasks, type: :hash
+
+      # Override default field-keyed setup to store the value as a single
+      # attribute. Handles both Hash and Array inputs.
+      # @return [void]
+      def setup_named_configurations
+        raw = hash_configuration
+        self.tasks = if raw.is_a?(Array)
+                       raw
+                     else
+                       (raw || {}).symbolize_keys
+                     end
+      end
+
+      # Returns true when no tasks are defined.
+      def blank?
+        tasks.blank?
+      end
+
+      # Returns the tasks value for backward compatibility.
+      # @return [Hash{Symbol => Object}, Array]
+      def symbolize_keys
+        tasks || {}
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/valid_if.rb b/app/models/option_configs/extra_option_configs/valid_if.rb
new file mode 100644
index 0000000000..09500f68d4
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/valid_if.rb
@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for validation trigger conditions.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the entire hash as a single direct attribute after validation and cascade.
+    #
+    # Handles:
+    # - Key validation against ValidValidIfTriggers
+    # - on_save cascade to on_create/on_update
+    #
+    # @example
+    #   vi = ValidIf.new(on_save: { all: { this: { field: 'is not null' } } })
+    #   vi.valid_if[:on_create] #=> { all: { this: { field: 'is not null' } } }
+    class ValidIf < BaseConfiguration
+      configure_direct :valid_if, type: :hash
+
+      validate :validate_keys
+
+      # Apply on_save cascade and store as valid_if attribute.
+      # Populates configurations for hash-like [] access.
+      # @return [void]
+      def setup_named_configurations
+        vi = hash_configuration.presence || {}
+        cascade_on_save(vi)
+        self.valid_if = vi
+        vi.each { |k, v| configurations[k] = v }
+      end
+
+      private
+
+      # Validate keys against the allowed set.
+      # @return [void]
+      def validate_keys
+        vi = valid_if
+        return if vi.blank? || vi.keys.empty?
+
+        invalid = vi.keys - OptionConfigs::ExtraOptions::ValidValidIfTriggers
+        return if invalid.empty?
+
+        errors.add(:valid_if,
+                   "contains invalid keys #{vi.keys} - expected only: #{OptionConfigs::ExtraOptions::ValidValidIfTriggers}")
+      end
+
+      # Cascade on_save into on_create and on_update as defaults.
+      # on_save values are merged as base, with specific key values taking priority.
+      # @param [Hash] vi - the valid_if hash (modified in place)
+      # @return [void]
+      def cascade_on_save(vi)
+        os = vi[:on_save]
+        return unless os
+
+        ou = vi[:on_update] || {}
+        oc = vi[:on_create] || {}
+        vi[:on_update] = os.merge(ou)
+        vi[:on_create] = os.merge(oc)
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/view_options.rb b/app/models/option_configs/extra_option_configs/view_options.rb
new file mode 100644
index 0000000000..c279a32a64
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/view_options.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for view options.
+    # Converted from ConfigBase to BaseConfiguration pattern.
+    # Stores the entire hash as a single direct attribute.
+    #
+    # @example
+    #   vo = ViewOptions.new(data_attribute: 'field_1', show_embedded: true)
+    #   vo.view_options #=> { data_attribute: 'field_1', show_embedded: true }
+    class ViewOptions < BaseConfiguration
+      configure_direct :view_options, type: :hash
+
+      # Store the entire input hash as the view_options attribute
+      # and populate configurations for hash-like [] access.
+      # @return [void]
+      def setup_named_configurations
+        self.view_options = hash_configuration.presence || {}
+        view_options.each { |k, v| configurations[k] = v }
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 5a7575e20d..b58dfa0832 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -13,29 +13,61 @@ class ExtraOptions < BaseOptions
     LibraryMatchRegex = /# @library\s+([^\s]+)\s+([^\s]+)\s*$/
     ValidFieldConfigs = %i[db_configs field_options labels caption_before dialog_before show_if].freeze
 
+    # Registry of configuration classes, in the order they must be initialized.
+    # Each entry maps a key (used in config_instances) to the config class.
+    # The order mirrors the original clean_... method call sequence.
+    def self.config_class_registry
+      {
+        fields: ExtraOptionConfigs::Fields,
+        field_configs: ExtraOptionConfigs::FieldConfigs,
+        label: ExtraOptionConfigs::Label,
+        caption_before: ExtraOptionConfigs::CaptionBefore,
+        dialog_before: ExtraOptionConfigs::DialogBefore,
+        labels: ExtraOptionConfigs::Labels,
+        show_if: ExtraOptionConfigs::ShowIf,
+        save_action: ExtraOptionConfigs::SaveAction,
+        view_options: ExtraOptionConfigs::ViewOptions,
+        db_configs: ExtraOptionConfigs::DbConfigs,
+        creatable_if: ExtraOptionConfigs::CreatableIf,
+        editable_if: ExtraOptionConfigs::EditableIf,
+        showable_if: ExtraOptionConfigs::ShowableIf,
+        valid_if: ExtraOptionConfigs::ValidIf,
+        filestore: ExtraOptionConfigs::Filestore,
+        field_options: ExtraOptionConfigs::FieldOptions,
+        embed: ExtraOptionConfigs::Embed,
+        references: ExtraOptionConfigs::References,
+        save_trigger: ExtraOptionConfigs::SaveTrigger,
+        batch_trigger: ExtraOptionConfigs::BatchTrigger,
+        config_trigger: ExtraOptionConfigs::ConfigTrigger,
+        preset_fields: ExtraOptionConfigs::PresetFields,
+        set_variables: ExtraOptionConfigs::SetVariable
+      }
+    end
+
     def self.base_key_attributes
       %i[
-        name label config_obj caption_before show_if resource_name resource_item_name save_action view_options
-        field_options dialog_before creatable_if editable_if showable_if add_reference_if valid_if
-        filestore labels fields button_label orig_config db_configs save_trigger embed references
-        show_if_condition_strings batch_trigger config_trigger preset_fields field_configs raw_field_configs
-        set_variables
+        name config_obj resource_name resource_item_name add_reference_if
+        button_label orig_config show_if_condition_strings raw_field_configs
       ]
     end
 
+    def self.config_class_attributes
+      config_class_registry.keys
+    end
+
     def self.add_key_attributes
       []
     end
 
     def self.key_attributes
-      base_key_attributes + add_key_attributes
+      base_key_attributes + config_class_attributes + add_key_attributes
     end
 
     def self.editable_attributes
       key_attributes - %i[name config_obj resource_name resource_item_name] + [:label]
     end
 
-    attr_accessor(*key_attributes, :def_item, :bad_ref_items)
+    attr_accessor(*key_attributes, :def_item, :bad_ref_items, :config_instances)
 
     #
     # Initialize a named option configuration, which may form one of many in a dynamic definition
@@ -46,6 +78,7 @@ def initialize(name, config, config_obj)
       super()
       @name = name
       @orig_config = config
+      @config_instances = {}
 
       self.def_item = @config_obj = config_obj
 
@@ -62,332 +95,47 @@ def initialize(name, config, config_obj)
       begin
         self.resource_name = "#{config_obj.full_implementation_class_name.ns_underscore}__#{self.name}"
         self.resource_item_name = resource_name
-        clean_fields_def
-        clean_field_configs
-
-        clean_label_def
-        clean_caption_before_def
-        clean_dialog_before_def
-        clean_labels_def
-        clean_show_if_def
-        clean_save_action_def
-        clean_view_options_def
-        clean_db_configs_def
-        clean_access_if_def
-        clean_valid_if_def
-        clean_filestore_def
-        clean_field_options_def
-        clean_embed_def
-        clean_references_def
-        clean_save_triggers
-        clean_batch_triggers
-        clean_config_triggers
-        clean_preset_fields
-        clean_set_variables_def
-
-        # Add the cleaned values back into field_configs - save a raw version for use elsewhere
-        # This needs to be "deep cloned", to avoid a simple clone just copying references
-        # Using Marshal for deep cloning is safe here since we're only operating on data already in memory
-        self.raw_field_configs = Marshal.load(Marshal.dump(field_configs))
-        add_field_configs_from_standalone_defs
-      rescue StandardError => e
-        Rails.logger.warn "Failed to initialize ExtraOptions for #{@name}: #{e}"
-        Rails.logger.warn e.short_string_backtrace
-        raise FphsOptionsGeneralError, "Failed to initialize ExtraOptions for #{@name}: #{e}", e.backtrace
-      end
-    end
-
-    # Defintion label
-    def clean_label_def
-      self.label ||= @name.to_s.humanize
-    end
-
-    def clean_caption_before_def
-      self.caption_before ||= {}
-      self.caption_before = self.caption_before.symbolize_keys
-
-      self.caption_before = self.caption_before.each do |k, v|
-        if v.is_a? String
-
-          v = Formatter::Substitution.text_to_html(v).strip
-
-          self.caption_before[k] = {
-            caption: v,
-            edit_caption: v,
-            show_caption: v,
-            new_caption: v
-          }
-        elsif v.is_a? Hash
-          v.each do |mode, modeval|
-            v[mode] = Formatter::Substitution.text_to_html(modeval).to_s.strip
-          end
-
-          v[:new_caption] = v[:edit_caption] unless v.key?(:new_caption)
-        end
-      end
-    end
-
-    def clean_dialog_before_def
-      self.dialog_before ||= {}
-      self.dialog_before = self.dialog_before.symbolize_keys
-
-      dialog_before.transform_values! { |v| v.is_a?(String) ? { name: v } : v }
-      dialog_before.each do |k, v|
-        unless v.is_a? Hash
-          failed_config :dialog_before,
-                        "dialog_before must be a Hash { name: '<template name>' } or String: #{k}",
-                        level: :error
-          next
-        end
-
-        name = v[:name]
-        mt = Admin::MessageTemplate.active.find_by(name:)
-        next if mt
-
-        failed_config :dialog_before,
-                      "dialog_before specifies a named message template that doesn't exist: #{name}",
-                      level: :warn
-      end
-    end
-
-    # Field labels definitions
-    def clean_labels_def
-      self.labels ||= {}
-      self.labels = self.labels.symbolize_keys
-    end
-
-    def clean_show_if_def
-      self.show_if ||= {}
-
-      show_if_condition_strings&.each do |fn, val|
-        # Generate a real show_if hash fs a condition string was provided
-        # and show if is not already set
-        next if val.nil? || val.empty? || self.show_if[fn]
-
-        begin
-          bl = Redcap::DataDictionaries::BranchingLogic.new(val)
-          sis = bl&.generate_show_if
-          self.show_if[fn] = sis if sis.present?
-        rescue StandardError => e
-          Rails.logger.warn "Failed to generate real show_if (in #{@config_obj&.resource_name}) " \
-                            "for #{fn}: #{val}\n#{e}"
-          self.show_if[fn] = { generate_show_if: "failed - #{e}" }
-        end
-      end
-
-      self.show_if = self.show_if.symbolize_keys
-    end
-
-    def clean_save_action_def
-      self.save_action ||= {}
-      self.save_action = self.save_action.symbolize_keys
 
-      # Make save_action.on_save the default for on_create and on_update
-      os = self.save_action[:on_save]
-      return unless os
-
-      ou = self.save_action[:on_update] || {}
-      oc = self.save_action[:on_create] || {}
-      self.save_action[:on_update] = os.merge(ou)
-      self.save_action[:on_create] = os.merge(oc)
-    end
-
-    def clean_view_options_def
-      self.view_options ||= {}
-      self.view_options = self.view_options.symbolize_keys
-    end
-
-    def clean_db_configs_def
-      self.db_configs ||= {}
-      @config_obj.db_columns ||= self.db_configs = self.db_configs.symbolize_keys if @config_obj.respond_to? :db_columns
-    end
-
-    #
-    # Clean the fields definition. This intentionally does not override the dynamic model field list
-    # or external identifier extra fields list. The fields definition is intended to be a list of
-    # fields that are presented to the end user, and may be a subset of the fields in the model.
-    def clean_fields_def
-      self.fields ||= []
-    end
-
-    def clean_field_options_def
-      self.field_options ||= {}
-      self.field_options = self.field_options.symbolize_keys
-
-      # Allow field_options.edit_as.alt_options to be an array
-      self.field_options.each do |k, v|
-        ao = nil
-        ao = v[:edit_as][:alt_options] if v && v[:edit_as]
-        next unless ao.is_a? Array
-
-        new_ao = {}
-        ao.each do |aov|
-          new_ao[aov.to_s.to_sym] = aov.to_s.downcase
-        end
-        self.field_options[k][:edit_as][:alt_options] = new_ao
-      end
-    end
-
-    def clean_filestore_def
-      self.filestore ||= {}
-      self.filestore = self.filestore.symbolize_keys
-    end
-
-    def clean_access_if_def
-      self.creatable_if ||= {}
-      self.creatable_if = self.creatable_if.symbolize_keys
-
-      self.editable_if ||= {}
-      self.editable_if = self.editable_if.symbolize_keys
-
-      self.showable_if ||= {}
-      self.showable_if = self.showable_if.symbolize_keys
-    end
-
-    def clean_valid_if_def
-      self.valid_if ||= {}
-      self.valid_if = self.valid_if.symbolize_keys
-
-      unless self.valid_if.keys.empty? || (self.valid_if.keys - ValidValidIfTriggers).empty?
-        failed_config :valid_if,
-                      "valid_if contains invalid keys #{valid_if.keys} - expected only:",
-                      extra_details: ValidValidIfTriggers
-      end
-
-      os = self.valid_if[:on_save]
-      return unless os
-
-      ou = self.valid_if[:on_update] || {}
-      oc = self.valid_if[:on_create] || {}
-      self.valid_if[:on_update] = os.merge(ou)
-      self.valid_if[:on_create] = os.merge(oc)
-    end
-
-    def clean_embed_def
-      return unless embed
-
-      if embed == 'default_embed_resource'
-        rn = config_obj.default_embed_resource_name(name)
-        self.embed = { resource_name: rn }
-      elsif embed.is_a?(String)
-        rn = embed
-        self.embed = { resource_name: rn }
-      else
-        rn = embed[:resource_name]
-      end
-
-      resource = Resources::Models.find_by(resource_name: rn)
-      embed[:resource_model_def] = resource
-
-      return if resource && resource[:model]
-
-      Rails.logger.warn "embed for #{rn} does not exist as a class in #{name} / #{config_obj.name}"
-      # Log this as a warning, not an error, since we are not able to control the order of items being created
-      # in an app import, and many references to underlying definitions will not yet have been created
-      failed_config :embed,
-                    "embed for #{rn} does not exist as a class in #{name} / #{config_obj.name}",
-                    level: :warn
-    end
-
-    def clean_references_def
-      return unless references
-
-      new_ref = {}
-      if references.is_a? Array
-        references.each do |refitem|
-          # Make all keys singular, to simplify configurations
-          add_refitem = {}
-          refitem.each do |k, _v|
-            if k.to_s != k.to_s.singularize
-              new_k = k.to_s.singularize.to_sym
-              add_refitem[new_k] = refitem.delete(k)
+        # Delegate to configuration classes in order
+        self.class.config_class_registry.each do |key, config_class|
+          if config_class < ExtraOptionConfigs::BaseConfiguration
+            # BaseConfiguration config: initialize with raw value
+            raw = send(key)
+            raw = config_class.prepare_config(raw, self) if config_class.respond_to?(:prepare_config)
+            instance = config_class.new(raw)
+
+            # Collect errors/warnings before potentially discarding the instance
+            collect_instance_errors(instance)
+
+            if config_class.store_processed_value?
+              # Value-preprocessor class: store the processed value, not the object
+              direct_attr = config_class.option_types[:direct]&.first || key
+              send("#{key}=", instance.send(direct_attr))
+            else
+              # Rich object class: store the BaseConfiguration instance
+              send("#{key}=", instance)
             end
+          else
+            # ConfigBase pattern: initialize with parent reference, apply back
+            ci = config_class.new(self)
+            ci.apply_to_parent!
+            @config_instances[key] = ci
           end
-
-          refitem.merge! add_refitem
-
-          refitem.each do |k, v|
-            vi = v[:add_with] && v[:add_with][:extra_log_type]
-            ckey = k.to_s
-            ckey += "_#{vi}" if vi
-            new_ref[ckey.to_sym] = { k => v }
-          end
-        end
-      else
-        new_ref = {}
-        fix_refs = {}
-
-        # Make all keys singular, to simplify configurations
-        # The changes can't be made directly inside the iteration, so handle it in two steps
-        references.each do |k, _v|
-          fix_refs[k] = references[k] if k.to_s != k.to_s.singularize
-        end
-
-        fix_refs.each do |k, _v|
-          new_k = k.to_s.singularize.to_sym
-          references[new_k] = references.delete(k)
-        end
-
-        references.each do |k, v|
-          vi = v[:add_with] && v[:add_with][:extra_log_type]
-          ckey = k.to_s
-          ckey += "_#{vi}" if vi
-          new_ref[ckey.to_sym] = { k => v }
         end
-      end
-
-      self.references = new_ref
-
-      references.each do |_k, refitem|
-        self.bad_ref_items = []
-        refitem.each do |mn, conf|
-          to_class = ModelReference.to_record_class_for_type(mn)
-
-          # Avoid breaking app type imports if the resource being pointed to in the reference
-          # hasn't been set up yet.
-          if to_class.nil? || (to_class.respond_to?(:definition) && !to_class.definition)
-            Rails.logger.warn "Definition for class #{to_class} is not set - skipping reference setup for #{mn}"
-            break
-          end
 
-          if to_class
-            elt = conf[:add_with] && conf[:add_with][:extra_log_type]
-            add_with_elt = nil
-            add_with_elt = to_class.human_name_for(elt) if elt && to_class.respond_to?(:human_name_for)
-            refitem[mn][:to_record_label] = conf[:result_label] || conf[:label] || add_with_elt || to_class.human_name
+        # Collect config errors/warnings from field-keyed config instances
+        collect_field_config_errors
 
-            if to_class.respond_to?(:no_master_association)
-              refitem[mn][:no_master_association] = to_class.no_master_association
-            end
+        # Handle config_obj mutation for db_configs (extracted from clean_db_configs_def)
+        config_obj.db_columns ||= db_configs.symbolize_keys if config_obj.respond_to?(:db_columns)
 
-            refitem[mn][:to_model_name_us] = to_class.to_s&.ns_underscore
-            refitem[mn][:to_model_class_name] = to_class.to_s
-            refitem[mn][:to_table_name] = to_class.table_name
-            nil
-
-            if to_class.respond_to?(:definition)
-              cd = to_class.definition
-              tsn = cd.schema_name
-              tct = cd.class.to_s
-              refitem[mn][:to_schema_name] = tsn
-              refitem[mn][:to_class_type] = tct
-            end
-          else
-            bad_ref_items << mn
-            Rails.logger.warn "extra log type reference for #{mn} does not exist as a class in #{name} / #{config_obj.name}"
-            Rails.logger.info 'Will clean up reference to avoid it being used again in this session'
-            # Log this as a warning, not an error, since we are not able to control the order of items being created
-            # in an app import, and many references to underlying definitions will not yet have been created
-            failed_config :references,
-                          "reference for #{mn} does not exist as a class in #{name} / #{config_obj.name}",
-                          level: :warn
-          end
-        end
-
-        # Cleanup bad items
-        bad_ref_items.each do |br|
-          refitem.delete(br)
-        end
+        # raw_field_configs is saved inside FieldConfigs.prepare_config (before standalone cleaning)
+        # Now merge cleaned standalone definitions into field_configs
+        add_field_configs_from_standalone_defs
+      rescue StandardError => e
+        Rails.logger.warn "Failed to initialize ExtraOptions for #{@name}: #{e}"
+        Rails.logger.warn e.short_string_backtrace
+        raise FphsOptionsGeneralError, "Failed to initialize ExtraOptions for #{@name}: #{e}", e.backtrace
       end
     end
 
@@ -405,137 +153,6 @@ def model_reference_config(model_reference)
         references[model_reference.to_record.class.name.ns_underscore.singularize.to_sym]
     end
 
-    def clean_save_triggers
-      self.save_trigger ||= {}
-      self.save_trigger = self.save_trigger.symbolize_keys
-
-      unless self.save_trigger.keys.empty? || (self.save_trigger.keys - ValidSaveTriggerTriggers).empty?
-        failed_config :save_trigger,
-                      "save_trigger contains invalid keys #{save_trigger.keys} - expected only:",
-                      extra_details: ValidSaveTriggerTriggers
-      end
-
-      # Make save_trigger.on_save the default for on_create and on_update
-      os = self.save_trigger[:on_save]
-      if os
-        os = [os] if os.is_a?(Hash)
-
-        ou = self.save_trigger[:on_update]
-        oc = self.save_trigger[:on_create]
-        ou = [ou] if ou.is_a?(Hash)
-        oc = [oc] if oc.is_a?(Hash)
-
-        ou ||= []
-        oc ||= []
-        self.save_trigger[:on_update] = os + ou
-        self.save_trigger[:on_create] = os + oc
-      end
-
-      self.save_trigger[:on_upload] ||= {}
-      self.save_trigger[:on_disable] ||= {}
-    end
-
-    def clean_batch_triggers
-      self.batch_trigger ||= {}
-      self.batch_trigger = self.batch_trigger.symbolize_keys
-      self.batch_trigger[:on_record] ||= {}
-    end
-
-    def clean_config_triggers
-      self.config_trigger ||= {}
-      self.config_trigger = self.config_trigger.symbolize_keys
-      od = self.config_trigger[:on_define] ||= []
-
-      self.config_trigger[:on_define] = [od] unless od.is_a?(Array)
-    end
-
-    def clean_preset_fields
-      self.preset_fields ||= {}
-      self.preset_fields = self.preset_fields.symbolize_keys
-    end
-
-    #
-    # Validate and clean the set_variables definition.
-    # set_variables accepts an ordered array of variable definitions,
-    # each with :name, :value, and optional :if condition.
-    def clean_set_variables_def
-      return if set_variables.blank?
-
-      unless set_variables.is_a?(Array)
-        failed_config :set_variables, 'must be an array of variable definitions'
-        self.set_variables = []
-        return
-      end
-
-      self.set_variables = set_variables.map do |entry|
-        entry = entry.symbolize_keys if entry.is_a?(Hash)
-        unless entry.is_a?(Hash) && entry[:name].present? && entry.key?(:value)
-          failed_config :set_variables, "each entry must have 'name' and 'value' keys"
-          next nil
-        end
-        entry
-      end.compact
-    end
-
-    def clean_field_configs
-      fla = fields
-      if field_configs.nil?
-        self.field_configs = {}
-      else
-        # 'field_configs' was explicitly set, so use it to set the appropriate configurations
-        # for each of the valid_configs
-        self.field_configs ||= {}
-        self.field_configs = self.field_configs.symbolize_keys
-        failed = false
-        field_configs.each do |fname, fconfig|
-          unless fconfig&.is_a? Hash
-            failed_config :field_configs, "field '#{fname}' is not a Hash"
-            failed = true
-            self.field_configs[fname] = {}
-            next
-          end
-
-          ValidFieldConfigs.each do |vc|
-            # For each of the ValidFieldConfigs, add the corresponding definition to the
-            #  named attribute
-            c = fconfig[vc]
-            next unless c
-
-            ivar = instance_variable_get("@#{vc}")
-            unless ivar
-              instance_variable_set("@#{vc}", {})
-              ivar = instance_variable_get("@#{vc}")
-            end
-
-            ivar.merge!(fname => c)
-          end
-        end
-
-        return if failed
-
-      end
-
-      # Build the list of errors from the explicitly defined field_configs
-      efs = field_configs.keys.map(&:to_s) - fla
-      if efs.present?
-        failed_config :field_configs, 'field_configs includes fields that are not in the field list:',
-                      extra_details: efs
-      end
-
-      field_configs.each do |fname, fconfig|
-        extra_keys = fconfig.keys - ValidFieldConfigs
-        next if extra_keys.empty?
-
-        failed_config :field_configs,
-                      "field_configs for #{fname} includes invalid keys: #{extra_keys} - expected only:",
-                      extra_details: ValidFieldConfigs
-      end
-
-      # Now that the field_configs errors have been checked for the explicitly definition,
-      # go ahead and merge in the values from the standalone definitions
-      add_field_configs_from_standalone_defs
-    end
-
     # Set field_configs from the configurations listed in ValidFieldConfigs
     # for each of the valid fields
     def add_field_configs_from_standalone_defs
@@ -557,6 +174,32 @@ def add_field_configs_from_standalone_defs
       end
     end
 
+    # Collect config errors and warnings from a single BaseConfiguration instance.
+    # Used during registry initialization to capture errors before the instance
+    # may be discarded (for store_processed_value? classes).
+    # @param instance [BaseConfiguration] the config instance
+    def collect_instance_errors(instance)
+      return unless instance.respond_to?(:config_errors)
+
+      config_errors.concat(instance.config_errors) if instance.config_errors.present?
+      config_warnings.concat(instance.config_warnings) if instance.config_warnings.present?
+    end
+
+    # Collect config errors and warnings from field-keyed config instances
+    # (those inheriting ExtraOptionConfigs::BaseConfiguration) into the
+    # parent ExtraOptions config_errors/config_warnings arrays.
+    def collect_field_config_errors
+      self.class.config_class_registry.each do |key, config_class|
+        next unless config_class < ExtraOptionConfigs::BaseConfiguration
+
+        config_instance = send(key)
+        next unless config_instance&.respond_to?(:config_errors)
+
+        config_errors.concat(config_instance.config_errors) if config_instance.config_errors.present?
+        config_warnings.concat(config_instance.config_warnings) if config_instance.config_warnings.present?
+      end
+    end
+
     # Check if any of the configs were bad
     # This should be extended to provide additional checks when options are saved
     # @todo - work out why the "raise" was disabled and whether it needs changing
diff --git a/app/models/validates/typed_attribute_validator.rb b/app/models/validates/typed_attribute_validator.rb
new file mode 100644
index 0000000000..d1c3219898
--- /dev/null
+++ b/app/models/validates/typed_attribute_validator.rb
@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Validates::TypedAttributeValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.nil?
+
+    expected_type = record.class.typed_attribute_types[attribute]
+    return if expected_type.nil?
+    return if value.is_a?(expected_type)
+
+    record.errors.add(attribute, :invalid_type,
+                      message: "must be a #{expected_type.name}, got #{value.class.name}")
+  end
+end
diff --git a/spec/models/calc_actions/calculate_spec.rb b/spec/models/calc_actions/calculate_spec.rb
index 1711122430..02fd5887d5 100644
--- a/spec/models/calc_actions/calculate_spec.rb
+++ b/spec/models/calc_actions/calculate_spec.rb
@@ -2976,7 +2976,7 @@ def setup_config(confy)
         }
       }
 
-      @alref.extra_log_type_config.clean_references_def
+      OptionConfigs::ExtraOptionConfigs::References.reprocess(@alref.extra_log_type_config)
       @alref.extra_log_type_config.editable_if = { always: true }
 
       ModelReference.create_with @alref, @alref1, force_create: true
@@ -3208,7 +3208,7 @@ def setup_config(confy)
           add: 'many'
         }
       }
-      @new_al.extra_log_type_config.clean_references_def
+      OptionConfigs::ExtraOptionConfigs::References.reprocess(@new_al.extra_log_type_config)
 
       @new_al0.extra_log_type_config.references = {
         activity_log__player_contact_phone: {
@@ -3216,7 +3216,7 @@ def setup_config(confy)
           add: 'many'
         }
       }
-      @new_al0.extra_log_type_config.clean_references_def
+      OptionConfigs::ExtraOptionConfigs::References.reprocess(@new_al0.extra_log_type_config)
 
       m = @new_al0.master
       m.current_user = @user
diff --git a/spec/models/option_configs/dynamic_model_options_spec.rb b/spec/models/option_configs/dynamic_model_options_spec.rb
index 5c6f2cb588..997edf09d6 100644
--- a/spec/models/option_configs/dynamic_model_options_spec.rb
+++ b/spec/models/option_configs/dynamic_model_options_spec.rb
@@ -513,11 +513,11 @@
 
     expect(dmdef.default_options.show_if[:test1]).to be_a Hash
     expect(dmdef.default_options.show_if[:test1]).to eq(never: true)
-    expect(dmdef.default_options.caption_before[:all_fields]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:all_fields]).to respond_to(:[])
     expect(dmdef.default_options.caption_before[:all_fields][:caption]).to eq('<p>show before all fields</p>')
-    expect(dmdef.default_options.caption_before[:test1]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:test1]).to respond_to(:[])
     expect(dmdef.default_options.caption_before[:test1][:caption]).to eq('<p>field_configs defined test1 caption</p>')
-    expect(dmdef.default_options.caption_before[:test2]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:test2]).to respond_to(:[])
     # The field_configs definition overrides any other standalone defs
     expect(dmdef.default_options.caption_before[:test2][:caption]).to eq('<p>has a caption before test2</p>')
     # The cleaned values go back into field_configs
@@ -578,11 +578,11 @@
     expect(dmdef.default_options.fields).to eq(dmdef.field_list_array)
     expect(dmdef.default_options.show_if[:test1]).to be_a Hash
     expect(dmdef.default_options.show_if[:test1]).to eq(never: true)
-    expect(dmdef.default_options.caption_before[:all_fields]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:all_fields]).to respond_to(:[])
     expect(dmdef.default_options.caption_before[:all_fields][:caption]).to eq('<p>show before all fields</p>')
-    expect(dmdef.default_options.caption_before[:test1]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:test1]).to respond_to(:[])
     expect(dmdef.default_options.caption_before[:test1][:caption]).to eq('<p>field_configs defined test1 caption</p>')
-    expect(dmdef.default_options.caption_before[:test2]).to be_a Hash
+    expect(dmdef.default_options.caption_before[:test2]).to respond_to(:[])
     expect(dmdef.default_options.caption_before[:test2][:caption]).to eq('<p>has a caption before test2</p>')
     expect(dmdef.default_options.field_configs[:test2][:caption_before]).to eq(dmdef.default_options.caption_before[:test2])
     expect(dmdef.default_options.raw_field_configs[:test2][:caption_before]).to eq('has a caption before test2')
@@ -591,11 +591,11 @@
     expect(view_1_options.fields).to be_empty
     expect(view_1_options.show_if[:test1]).to be_a Hash
     expect(view_1_options.show_if[:test1]).to eq(never: true)
-    expect(view_1_options.caption_before[:all_fields]).to be_a Hash
+    expect(view_1_options.caption_before[:all_fields]).to respond_to(:[])
     expect(view_1_options.caption_before[:all_fields][:caption]).to eq('<p>show before all fields in view_1</p>')
-    expect(view_1_options.caption_before[:test1]).to be_a Hash
+    expect(view_1_options.caption_before[:test1]).to respond_to(:[])
     expect(view_1_options.caption_before[:test1][:caption]).to eq('<p>field_configs defined test1 caption</p>')
-    expect(view_1_options.caption_before[:test2]).to be_a Hash
+    expect(view_1_options.caption_before[:test2]).to respond_to(:[])
     expect(view_1_options.caption_before[:test2][:caption]).to eq('<p>has a caption before test2</p>')
     expect(view_1_options.caption_before[:test2][:caption]).to eq('<p>has a caption before test2</p>')
 
diff --git a/spec/models/option_configs/extra_option_configs_spec.rb b/spec/models/option_configs/extra_option_configs_spec.rb
new file mode 100644
index 0000000000..1e9118b3c4
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs_spec.rb
@@ -0,0 +1,2099 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Phase 2 of issue #986: Verify configuration classes for ExtraOptions clean methods.
+# Each top-level configuration area from ExtraOptions has a dedicated configuration class
+# under OptionConfigs::ExtraOptionConfigs:: namespace. These tests verify:
+# - All configuration classes exist with correct inheritance
+# - Each class declares its managed attributes
+# - ExtraOptions stores config instances after initialization
+# - Config instance attribute values match ExtraOptions attribute values
+# - ActiveModel::Validations is available on all config classes for reflection
+# - CaptionBefore uses BaseConfiguration/NamedConfiguration pattern with hash compatibility
+RSpec.describe 'ExtraOptionConfigs configuration classes', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  # Helper: update the DynamicModel with given YAML options and return the first option config
+  def config_for(yaml)
+    @dm.update!(options: yaml, current_admin: @admin)
+    @dm.option_configs.first
+  end
+
+  # All expected config classes with their managed attributes.
+  # Registry key must match the ExtraOptions attribute name.
+  # Class names are singular (SaveTrigger not SaveTriggers).
+  # AccessIf is split into CreatableIf, EditableIf, ShowableIf.
+  EXPECTED_CONFIG_CLASSES = {
+    fields: :Fields,
+    label: :Label,
+    caption_before: :CaptionBefore,
+    dialog_before: :DialogBefore,
+    labels: :Labels,
+    show_if: :ShowIf,
+    save_action: :SaveAction,
+    view_options: :ViewOptions,
+    db_configs: :DbConfigs,
+    creatable_if: :CreatableIf,
+    editable_if: :EditableIf,
+    showable_if: :ShowableIf,
+    valid_if: :ValidIf,
+    filestore: :Filestore,
+    field_options: :FieldOptions,
+    embed: :Embed,
+    references: :References,
+    save_trigger: :SaveTrigger,
+    batch_trigger: :BatchTrigger,
+    config_trigger: :ConfigTrigger,
+    preset_fields: :PresetFields,
+    set_variables: :SetVariable,
+    field_configs: :FieldConfigs
+  }.freeze
+
+  # ──────────────────────────────────────────────────────────────
+  # ConfigBase
+  # ──────────────────────────────────────────────────────────────
+  describe 'OptionConfigs::ExtraOptionConfigs::ConfigBase' do
+    it 'exists as a class' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to be_a Class
+    end
+
+    it 'includes ActiveModel::Validations' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase.ancestors).to include(ActiveModel::Validations)
+    end
+
+    it 'provides managed_attributes class method' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to respond_to(:managed_attributes)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Registry key alignment and config_class_attributes
+  # ──────────────────────────────────────────────────────────────
+  describe 'config_class_registry and config_class_attributes' do
+    it 'config_class_registry keys match ExtraOptions attribute names' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      EXPECTED_CONFIG_CLASSES.each_key do |attr_key|
+        expect(registry).to have_key(attr_key),
+                            "Expected config_class_registry to have key :#{attr_key}"
+      end
+    end
+
+    it 'registry class names are singular (no trailing s on Triggers/Variables)' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      # These classes should exist with singular names
+      expect(registry[:save_trigger].name).to include('SaveTrigger')
+      expect(registry[:save_trigger].name).not_to include('SaveTriggers')
+      expect(registry[:batch_trigger].name).to include('BatchTrigger')
+      expect(registry[:batch_trigger].name).not_to include('BatchTriggers')
+      expect(registry[:config_trigger].name).to include('ConfigTrigger')
+      expect(registry[:config_trigger].name).not_to include('ConfigTriggers')
+      expect(registry[:set_variables].name).to include('SetVariable')
+    end
+
+    it 'AccessIf is split into CreatableIf, EditableIf, ShowableIf' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      expect(registry).not_to have_key(:access_if)
+      expect(registry).to have_key(:creatable_if)
+      expect(registry).to have_key(:editable_if)
+      expect(registry).to have_key(:showable_if)
+    end
+
+    it 'provides config_class_attributes derived from registry keys' do
+      attrs = OptionConfigs::ExtraOptions.config_class_attributes
+      expect(attrs).to be_an Array
+      EXPECTED_CONFIG_CLASSES.each_key do |key|
+        expect(attrs).to include(key),
+                         "Expected config_class_attributes to include :#{key}"
+      end
+    end
+
+    it 'base_key_attributes does not include config class attributes' do
+      base = OptionConfigs::ExtraOptions.base_key_attributes
+      config_attrs = OptionConfigs::ExtraOptions.config_class_attributes
+      overlap = base & config_attrs
+      expect(overlap).to be_empty,
+                         "base_key_attributes should not overlap config_class_attributes, but found: #{overlap}"
+    end
+
+    it 'key_attributes includes both base and config class attributes' do
+      all = OptionConfigs::ExtraOptions.key_attributes
+      base = OptionConfigs::ExtraOptions.base_key_attributes
+      config = OptionConfigs::ExtraOptions.config_class_attributes
+      expect(all).to include(*base)
+      expect(all).to include(*config)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # configure_typed_attribute in OptionsHandler
+  # ──────────────────────────────────────────────────────────────
+  describe 'configure_typed_attribute' do
+    it 'is available as a class method via OptionsHandler' do
+      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_typed_attribute)
+    end
+
+    it 'registers the attribute in option_types[:typed]' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+      end
+      expect(test_class.option_types[:typed]).to include(:test_conditions)
+    end
+
+    it 'stores the type class reference in typed_attribute_types' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+      end
+      expect(test_class.typed_attribute_types[:test_conditions]).to eq(OptionConfigs::ExtraOptionConfigs::IfCondition)
+    end
+
+    it 'auto-initializes the attribute from hash configuration' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+
+        def config_text=(_value); end
+      end
+      instance = test_class.new(nil, use_hash_config: { test_conditions: { always: true } })
+      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
+      expect(instance.test_conditions.conditions).to eq(always: true)
+    end
+
+    it 'handles nil hash configuration value gracefully' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+
+        def config_text=(_value); end
+      end
+      instance = test_class.new(nil, use_hash_config: { test_conditions: nil })
+      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
+      expect(instance.test_conditions).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # IfCondition configuration class
+  # ──────────────────────────────────────────────────────────────
+  describe 'IfCondition' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::IfCondition }
+
+    it 'exists under ExtraOptionConfigs namespace' do
+      expect(klass).to be_a Class
+    end
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:conditions)
+      expect(klass.direct_types[:conditions]).to eq(:hash)
+    end
+
+    it 'stores entire hash as single conditions attribute' do
+      instance = klass.new(always: true, user_is_creator: true)
+      expect(instance.conditions).to eq(always: true, user_is_creator: true)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'returns not blank when initialized with data' do
+      instance = klass.new(always: true)
+      expect(instance).not_to be_blank
+    end
+
+    it 'symbolizes keys on initialization' do
+      instance = klass.new('always' => true)
+      expect(instance.conditions).to have_key(:always)
+    end
+
+    it 'handles nil initialization' do
+      instance = klass.new(nil)
+      expect(instance.conditions).to eq({})
+      expect(instance).to be_blank
+    end
+
+    it 'supports symbolize_keys for backward compatibility' do
+      instance = klass.new(always: true, never: false)
+      expect(instance.symbolize_keys).to eq(always: true, never: false)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # TriggerTasks configuration class
+  # ──────────────────────────────────────────────────────────────
+  describe 'TriggerTasks' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::TriggerTasks }
+
+    it 'exists under ExtraOptionConfigs namespace' do
+      expect(klass).to be_a Class
+    end
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:tasks)
+      expect(klass.direct_types[:tasks]).to eq(:hash)
+    end
+
+    it 'stores entire hash as single tasks attribute' do
+      instance = klass.new(notify: { type: 'email' }, update_this: { field: 'val' })
+      expect(instance.tasks).to eq(notify: { type: 'email' }, update_this: { field: 'val' })
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'handles nil initialization' do
+      instance = klass.new(nil)
+      expect(instance.tasks).to eq({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys on initialization' do
+      instance = klass.new('notify' => { 'type' => 'email' })
+      expect(instance.tasks).to have_key(:notify)
+    end
+
+    it 'supports symbolize_keys for backward compatibility' do
+      instance = klass.new(notify: { type: 'email' })
+      expect(instance.symbolize_keys).to eq(notify: { type: 'email' })
+    end
+
+    # Array support for save_trigger values (on_create, on_update, etc.)
+    it 'stores array value as tasks when initialized with an array' do
+      arr = [{ notify: { type: 'email' } }, { update_this: { field: 'val' } }]
+      instance = klass.new(arr)
+      expect(instance.tasks).to eq(arr)
+    end
+
+    it 'returns not blank when initialized with a non-empty array' do
+      instance = klass.new([{ notify: { type: 'email' } }])
+      expect(instance).not_to be_blank
+    end
+
+    it 'returns blank when initialized with an empty array' do
+      instance = klass.new([])
+      expect(instance).to be_blank
+    end
+
+    it 'symbolize_keys returns the array as-is when tasks is an array' do
+      arr = [{ notify: { type: 'email' } }]
+      instance = klass.new(arr)
+      expect(instance.symbolize_keys).to eq(arr)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # BatchTrigger converted to BaseConfiguration with TriggerTasks
+  # ──────────────────────────────────────────────────────────────
+  describe 'BatchTrigger (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::BatchTrigger }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares on_record as a typed attribute with TriggerTasks type' do
+      expect(klass.option_types[:typed]).to include(:on_record)
+      expect(klass.typed_attribute_types[:on_record]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+    end
+
+    it 'initializes on_record as a TriggerTasks instance from hash' do
+      instance = klass.new(on_record: { notify: { type: 'email' } })
+      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_record.tasks).to eq(notify: { type: 'email' })
+    end
+
+    it 'initializes on_record as blank TriggerTasks when not provided' do
+      instance = klass.new({})
+      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_record).to be_blank
+    end
+
+    it 'supports hash-like bracket access for on_record' do
+      instance = klass.new(on_record: { action: 'process' })
+      expect(instance[:on_record]).to be_a(Hash)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # configure_direct in OptionsHandler
+  # ──────────────────────────────────────────────────────────────
+  describe 'configure_direct' do
+    it 'is available as a class method via OptionsHandler' do
+      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_direct)
+    end
+
+    it 'records the direct type in option_types[:direct]' do
+      # Label uses configure_direct type: :string
+      label_klass = OptionConfigs::ExtraOptionConfigs::Label
+      expect(label_klass.option_types[:direct]).to be_present
+    end
+
+    it 'Fields declares configure_direct type: :array' do
+      fields_klass = OptionConfigs::ExtraOptionConfigs::Fields
+      expect(fields_klass.option_types[:direct]).to include(:fields)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # CreatableIf, EditableIf, ShowableIf (split from AccessIf)
+  # Note: detailed conversion tests are in 'if_condition classes (converted to BaseConfiguration)' section above
+  # ──────────────────────────────────────────────────────────────
+  describe 'if_condition classes (split from AccessIf)' do
+    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+
+        it 'exists under ExtraOptionConfigs namespace' do
+          expect(klass).to be_a Class
+        end
+
+        it 'uses configure_direct with type :hash' do
+          expect(klass.option_types[:direct]).to be_present
+        end
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # SaveTrigger converted to BaseConfiguration with TriggerTasks
+  # ──────────────────────────────────────────────────────────────
+  describe 'SaveTrigger (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveTrigger }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares all trigger keys as typed attributes with TriggerTasks type' do
+      %i[on_create on_update on_save on_upload on_disable before_save].each do |key|
+        expect(klass.option_types[:typed]).to include(key),
+                                              "Expected option_types[:typed] to include :#{key}"
+        expect(klass.typed_attribute_types[key]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks),
+                                                    "Expected typed_attribute_types[:#{key}] to be TriggerTasks"
+      end
+    end
+
+    it 'initializes trigger keys as TriggerTasks instances' do
+      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
+      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_create.tasks).to eq([{ notify: { type: 'email' } }])
+    end
+
+    it 'defaults missing trigger keys to blank TriggerTasks' do
+      instance = klass.new({})
+      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_create).to be_blank
+      expect(instance.on_upload).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_upload).to be_blank
+    end
+
+    it 'supports hash-like bracket access for trigger keys' do
+      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
+      expect(instance[:on_create]).to be_a(Array)
+    end
+
+    it 'cascades on_save into on_create and on_update' do
+      instance = klass.new(on_save: { notify: { type: 'email' } })
+      expect(instance.on_create.tasks).to be_an Array
+      expect(instance.on_create.tasks.length).to eq 1
+      expect(instance.on_update.tasks).to be_an Array
+      expect(instance.on_update.tasks.length).to eq 1
+    end
+
+    it 'appends on_save to existing on_create and on_update' do
+      instance = klass.new(
+        on_save: { notify: { type: 'email' } },
+        on_create: { create_action: { type: 'special' } }
+      )
+      expect(instance.on_create.tasks).to be_an Array
+      expect(instance.on_create.tasks.length).to eq 2
+      expect(instance.on_update.tasks).to be_an Array
+      expect(instance.on_update.tasks.length).to eq 1
+    end
+
+    it 'validates keys against ValidSaveTriggerTriggers' do
+      instance = klass.new(on_invalid_trigger: { something: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :save_trigger }
+      expect(err).to be_present
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ViewOptions converted to BaseConfiguration (simple direct hash)
+  # ──────────────────────────────────────────────────────────────
+  describe 'ViewOptions (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::ViewOptions }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:view_options)
+    end
+
+    it 'stores entire hash as single attribute' do
+      instance = klass.new(data_attribute: 'field_1', show_embedded: true)
+      expect(instance.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(data_attribute: 'test')
+      expect(instance.symbolize_keys).to eq(data_attribute: 'test')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Filestore converted to BaseConfiguration (simple direct hash)
+  # ──────────────────────────────────────────────────────────────
+  describe 'Filestore (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::Filestore }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:filestore)
+    end
+
+    it 'stores entire hash as single attribute' do
+      instance = klass.new(container: { path: '/test' })
+      expect(instance.filestore).to eq(container: { path: '/test' })
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(container: {})
+      expect(instance.symbolize_keys).to eq(container: {})
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ConfigTrigger converted to BaseConfiguration
+  # ──────────────────────────────────────────────────────────────
+  describe 'ConfigTrigger (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::ConfigTrigger }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares on_define as a typed attribute with TriggerTasks type' do
+      expect(klass.option_types[:typed]).to include(:on_define)
+      expect(klass.typed_attribute_types[:on_define]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+    end
+
+    it 'wraps non-array on_define in an array' do
+      instance = klass.new(on_define: { action: 'do_something' })
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define.tasks).to be_an Array
+      expect(instance.on_define.tasks.length).to eq 1
+    end
+
+    it 'preserves array on_define' do
+      instance = klass.new(on_define: [{ action: 'first' }, { action: 'second' }])
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define.tasks).to be_an Array
+      expect(instance.on_define.tasks.length).to eq 2
+    end
+
+    it 'defaults on_define to blank TriggerTasks when not provided' do
+      instance = klass.new({})
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define).to be_blank
+    end
+
+    it 'supports hash-like bracket access' do
+      instance = klass.new(on_define: [{ action: 'test' }])
+      expect(instance[:on_define]).to be_a(Array)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # SaveAction converted to BaseConfiguration (simple direct hash with cascade)
+  # ──────────────────────────────────────────────────────────────
+  describe 'SaveAction (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveAction }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:save_action)
+    end
+
+    it 'cascades on_save to on_create and on_update' do
+      instance = klass.new(on_save: { label: 'Saved' })
+      expect(instance.save_action[:on_create]).to eq(label: 'Saved')
+      expect(instance.save_action[:on_update]).to eq(label: 'Saved')
+    end
+
+    it 'merges on_save into existing on_create and on_update' do
+      instance = klass.new(on_save: { label: 'Default', notify: true }, on_create: { label: 'Created' })
+      expect(instance.save_action[:on_create][:label]).to eq 'Created'
+      expect(instance.save_action[:on_create][:notify]).to eq true
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(label: 'Test')
+      expect(instance.symbolize_keys).to eq(label: 'Test')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ValidIf converted to BaseConfiguration (direct hash with cascade + validation)
+  # ──────────────────────────────────────────────────────────────
+  describe 'ValidIf (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::ValidIf }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:valid_if)
+    end
+
+    it 'cascades on_save to on_create and on_update' do
+      instance = klass.new(on_save: { all: { this: { test1: 'is not null' } } })
+      expect(instance.valid_if[:on_create]).to eq(instance.valid_if[:on_save])
+      expect(instance.valid_if[:on_update]).to eq(instance.valid_if[:on_save])
+    end
+
+    it 'validates keys against ValidValidIfTriggers' do
+      instance = klass.new(on_invalid_key: { always: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :valid_if }
+      expect(err).to be_present
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(on_save: { always: true })
+      expect(instance.symbolize_keys).to have_key(:on_save)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # SetVariable converted to BaseConfiguration (direct array with validation)
+  # ──────────────────────────────────────────────────────────────
+  describe 'SetVariable (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::SetVariable }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :array' do
+      expect(klass.option_types[:direct]).to include(:set_variables)
+    end
+
+    it 'stores valid array entries' do
+      instance = klass.new([{ name: 'var1', value: 'val1' }])
+      expect(instance.set_variables).to be_an Array
+      expect(instance.set_variables.length).to eq 1
+      expect(instance.set_variables[0][:name]).to eq 'var1'
+    end
+
+    it 'reports error when value is not an array' do
+      instance = klass.new(name: 'var1', value: 'val1')
+      expect(instance.config_errors).not_to be_empty
+    end
+
+    it 'filters out invalid entries' do
+      instance = klass.new([{ name: 'valid', value: 'val' }, { no_name: 'invalid' }])
+      expect(instance.set_variables.length).to eq 1
+    end
+
+    it 'returns blank when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Fields (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'Fields (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::Fields }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :array' do
+      expect(klass.option_types[:direct]).to include(:fields)
+    end
+
+    it 'stores the array as fields attribute' do
+      instance = klass.new(%w[field1 field2])
+      expect(instance.fields).to eq %w[field1 field2]
+    end
+
+    it 'defaults to empty array when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.fields).to eq []
+    end
+
+    it 'returns blank when initialized with empty array' do
+      instance = klass.new([])
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Label (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'Label (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::Label }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :string' do
+      expect(klass.option_types[:direct]).to include(:label)
+    end
+
+    it 'stores the string as label attribute' do
+      instance = klass.new('My Label')
+      expect(instance.label).to eq 'My Label'
+    end
+
+    it 'defaults to empty string when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.label).to eq ''
+    end
+
+    it 'uses prepare_config to default to humanized name from parent' do
+      expect(klass).to respond_to(:prepare_config)
+    end
+
+    it 'integration: defaults label to humanized name when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+      YAML
+      # Label uses store_processed_value?, so eo.label is a plain string
+      expect(eo.label).to eq 'Default'
+    end
+
+    it 'integration: preserves explicit label' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Custom Label
+          fields:
+            - test1
+      YAML
+      expect(eo.label).to eq 'Custom Label'
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # CreatableIf, EditableIf, ShowableIf (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'if_condition classes (converted to BaseConfiguration)' do
+    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+        let(:attr_name) { class_name.to_s.underscore.to_sym }
+
+        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+        end
+
+        it 'does not inherit from ConfigBase' do
+          expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+        end
+
+        it 'declares configure_direct with type :hash' do
+          expect(klass.option_types[:direct]).to include(attr_name)
+        end
+
+        it 'stores the hash as the attribute' do
+          instance = klass.new(always: true)
+          expect(instance.send(attr_name)).to eq(always: true)
+        end
+
+        it 'supports hash-like bracket access' do
+          instance = klass.new(always: true)
+          expect(instance[:always]).to eq true
+        end
+
+        it 'defaults to empty hash when initialized with nil' do
+          instance = klass.new(nil)
+          expect(instance.send(attr_name)).to eq({})
+          expect(instance).to be_blank
+        end
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Embed (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'Embed (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::Embed }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:embed)
+    end
+
+    it 'stores resource_name from string input' do
+      instance = klass.new('some_resource')
+      expect(instance.embed[:resource_name]).to eq 'some_resource'
+    end
+
+    it 'stores resource_name from hash input' do
+      instance = klass.new(resource_name: 'some_resource')
+      expect(instance.embed[:resource_name]).to eq 'some_resource'
+    end
+
+    it 'returns blank when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # FieldConfigs (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'FieldConfigs (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldConfigs }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:field_configs)
+    end
+
+    it 'stores the hash as field_configs attribute' do
+      instance = klass.new(test1: { caption_before: 'Test' })
+      expect(instance.field_configs).to eq(test1: { caption_before: 'Test' })
+    end
+
+    it 'defaults to empty hash when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.field_configs).to eq({})
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # References (converted to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'References (converted to BaseConfiguration)' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::References }
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:references)
+    end
+
+    it 'defaults to nil when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.references).to be_nil
+    end
+  end
+
+  # Config classes that still use ConfigBase pattern
+  CONFIGBASE_CLASSES = {}.freeze
+
+  # Config classes that use the field-keyed BaseConfiguration pattern
+  FIELD_KEYED_CLASSES = %i[CaptionBefore Labels DialogBefore ShowIf FieldOptions DbConfigs PresetFields].freeze
+
+  # Config classes converted to BaseConfiguration with typed or direct attributes
+  TYPED_CONFIG_CLASSES = %i[
+    BatchTrigger SaveTrigger ViewOptions Filestore ConfigTrigger SaveAction ValidIf SetVariable
+    Fields Label CreatableIf EditableIf ShowableIf Embed FieldConfigs References
+  ].freeze
+
+  # ──────────────────────────────────────────────────────────────
+  # Configuration classes: existence, inheritance, managed_attributes
+  # ──────────────────────────────────────────────────────────────
+  describe 'ConfigBase configuration classes exist with correct structure' do
+    CONFIGBASE_CLASSES.each do |class_name, expected_attributes|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+
+        it 'exists under OptionConfigs::ExtraOptionConfigs namespace' do
+          expect(klass).to be_a Class
+        end
+
+        it 'inherits from ConfigBase' do
+          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+        end
+
+        it "declares managed attributes #{expected_attributes}" do
+          expected_attributes.each do |attr|
+            expect(klass.managed_attributes).to include(attr),
+                                                "Expected #{class_name}.managed_attributes to include :#{attr}"
+          end
+        end
+
+        it 'includes ActiveModel::Validations' do
+          expect(klass.ancestors).to include(ActiveModel::Validations)
+        end
+
+        it 'responds to validators for reflection' do
+          expect(klass).to respond_to(:validators)
+        end
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # CaptionBefore: BaseConfiguration/NamedConfiguration pattern
+  # ──────────────────────────────────────────────────────────────
+  describe 'CaptionBefore uses BaseConfiguration pattern' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::CaptionBefore }
+
+    it 'inherits from BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::BaseConfiguration)
+    end
+
+    it 'defines a NamedConfiguration inner class' do
+      expect(klass.const_defined?(:NamedConfiguration)).to be true
+    end
+
+    it 'NamedConfiguration inherits from BaseNamedConfiguration' do
+      expect(klass::NamedConfiguration.ancestors).to include(OptionConfigs::BaseNamedConfiguration)
+    end
+
+    it 'NamedConfiguration declares caption attributes via configure_attributes' do
+      expected = %i[caption edit_caption show_caption new_caption]
+      expected.each do |attr|
+        expect(klass::NamedConfiguration.option_types[:simple]).to include(attr)
+      end
+    end
+
+    context 'initialized with a raw hash' do
+      let(:raw_config) { { test1: 'Simple text', test2: { caption: 'Cap', edit_caption: 'Edit' } } }
+      let(:instance) { klass.new(raw_config) }
+
+      it 'creates named configurations for each field' do
+        expect(instance.configurations).to have_key(:test1)
+        expect(instance.configurations).to have_key(:test2)
+      end
+
+      it 'stores NamedConfiguration objects in configurations' do
+        expect(instance.configurations[:test1]).to be_a klass::NamedConfiguration
+        expect(instance.configurations[:test2]).to be_a klass::NamedConfiguration
+      end
+
+      it 'preprocesses string values into all caption modes' do
+        nc = instance.configurations[:test1]
+        expect(nc.caption).to be_present
+        expect(nc.edit_caption).to eq nc.caption
+        expect(nc.show_caption).to eq nc.caption
+        expect(nc.new_caption).to eq nc.caption
+      end
+
+      it 'preserves hash values with individual mode settings' do
+        nc = instance.configurations[:test2]
+        expect(nc.caption).to include('Cap')
+        expect(nc.edit_caption).to include('Edit')
+      end
+
+      it 'defaults new_caption to edit_caption when not specified' do
+        nc = instance.configurations[:test2]
+        expect(nc.new_caption).to eq nc.edit_caption
+      end
+    end
+
+    context 'hash-like interface' do
+      let(:raw_config) { { test1: 'Caption text' } }
+      let(:instance) { klass.new(raw_config) }
+
+      it '[] returns a NamedConfiguration for a given field' do
+        expect(instance[:test1]).to be_a klass::NamedConfiguration
+      end
+
+      it '[] returns nil for missing fields' do
+        expect(instance[:nonexistent]).to be_nil
+      end
+
+      it 'NamedConfiguration supports [] for attribute access' do
+        nc = instance[:test1]
+        expect(nc[:caption]).to eq nc.caption
+        expect(nc[:edit_caption]).to eq nc.edit_caption
+      end
+
+      it 'supports keys method' do
+        expect(instance.keys).to eq [:test1]
+      end
+
+      it 'supports each iteration' do
+        yielded = []
+        instance.each { |k, v| yielded << [k, v.class] }
+        expect(yielded).to eq [[:test1, klass::NamedConfiguration]]
+      end
+
+      it 'supports blank? for empty config' do
+        empty = klass.new({})
+        expect(empty).to be_blank
+      end
+
+      it 'supports blank? for populated config' do
+        expect(instance).not_to be_blank
+      end
+
+      it 'supports merge! with a plain hash' do
+        instance.merge!(test2: { caption: 'New cap' })
+        expect(instance[:test2]).to be_a klass::NamedConfiguration
+        expect(instance[:test2].caption).to include('New cap')
+      end
+
+      it 'supports []= assignment' do
+        instance[:test3] = { caption: 'Assigned' }
+        expect(instance[:test3]).to be_a klass::NamedConfiguration
+        expect(instance[:test3].caption).to include('Assigned')
+      end
+
+      it 'symbolize_keys returns a plain Hash for backward compat' do
+        result = instance.symbolize_keys
+        expect(result).to be_a Hash
+        expect(result[:test1]).to be_a Hash
+        expect(result[:test1]).to have_key(:caption)
+      end
+    end
+
+    context 'JSON serialization' do
+      let(:raw_config) { { test1: 'Cap text', test2: { caption: 'C', edit_caption: 'E' } } }
+      let(:instance) { klass.new(raw_config) }
+
+      it 'as_json returns a plain nested hash' do
+        json = instance.as_json
+        expect(json).to be_a Hash
+        expect(json['test1']).to be_a Hash
+        expect(json['test1']).to have_key('caption')
+      end
+
+      it 'to_json produces valid JSON matching the expected format' do
+        json_str = instance.to_json
+        parsed = JSON.parse(json_str)
+        expect(parsed).to have_key('test1')
+        expect(parsed['test1']).to have_key('caption')
+      end
+
+      it 'empty config serializes to empty JSON object' do
+        empty = klass.new({})
+        expect(JSON.parse(empty.to_json)).to eq({})
+      end
+    end
+
+    context 'unrecognized NamedConfiguration attributes' do
+      it 'reports a config warning when a field has an unrecognized attribute' do
+        raw = { test1: { caption: 'Valid', bogus_attr: 'Invalid' } }
+        instance = klass.new(raw)
+        expect(instance.config_warnings).to be_present,
+                                            'Expected config_warnings for unrecognized attribute bogus_attr'
+        warning_messages = instance.config_warnings.map { |w| w[:message] }
+        expect(warning_messages.any? { |m| m.include?('bogus_attr') }).to be(true),
+                                                                          "Expected warning mentioning 'bogus_attr', got: #{warning_messages}"
+      end
+
+      it 'does not report warnings for valid attributes only' do
+        raw = { test1: { caption: 'Cap', edit_caption: 'Edit', show_caption: 'Show', new_caption: 'New' } }
+        instance = klass.new(raw)
+        expect(instance.config_warnings).to be_empty,
+                                            "Expected no config_warnings for valid attributes, got: #{instance.config_warnings}"
+      end
+
+      it 'does not report warnings for string values (auto-expanded)' do
+        raw = { test1: 'Simple text' }
+        instance = klass.new(raw)
+        expect(instance.config_warnings).to be_empty,
+                                            "Expected no config_warnings for string value, got: #{instance.config_warnings}"
+      end
+
+      it 'reports multiple unrecognized attributes in a single field' do
+        raw = { test1: { caption: 'Valid', bad1: 'x', bad2: 'y' } }
+        instance = klass.new(raw)
+        warning_messages = instance.config_warnings.map { |w| w[:message] }
+        expect(warning_messages.any? { |m| m.include?('bad1') }).to be(true)
+        expect(warning_messages.any? { |m| m.include?('bad2') }).to be(true)
+      end
+
+      it 'reports unrecognized attributes across multiple fields' do
+        raw = { field1: { caption: 'OK', nope1: 'x' }, field2: { bogus2: 'y' } }
+        instance = klass.new(raw)
+        warning_messages = instance.config_warnings.map { |w| w[:message] }
+        expect(warning_messages.any? { |m| m.include?('nope1') }).to be(true)
+        expect(warning_messages.any? { |m| m.include?('bogus2') }).to be(true)
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Field-keyed classes inheriting ExtraOptionConfigs::BaseConfiguration
+  # ──────────────────────────────────────────────────────────────
+  describe 'Field-keyed BaseConfiguration classes' do
+    FIELD_KEYED_CLASSES.each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+
+        it 'exists under OptionConfigs::ExtraOptionConfigs namespace' do
+          expect(klass).to be_a Class
+        end
+
+        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+        end
+
+        it 'supports hash-like interface ([], keys, key?, blank?, merge!, symbolize_keys)' do
+          instance = klass.new({})
+          expect(instance).to respond_to(:[], :keys, :key?, :blank?, :merge!, :symbolize_keys)
+        end
+
+        it 'is blank when initialized with empty hash' do
+          instance = klass.new({})
+          expect(instance).to be_blank
+        end
+
+        it 'supports JSON serialization' do
+          instance = klass.new({})
+          expect(JSON.parse(instance.to_json)).to eq({})
+        end
+
+        it 'provides error collection arrays' do
+          instance = klass.new({})
+          expect(instance.config_errors).to eq([])
+          expect(instance.config_warnings).to eq([])
+        end
+      end
+    end
+
+    context 'Labels stores plain string values' do
+      let(:instance) { OptionConfigs::ExtraOptionConfigs::Labels.new(field1: 'Label One', field2: 'Label Two') }
+
+      it 'returns string values via bracket access' do
+        expect(instance[:field1]).to eq 'Label One'
+        expect(instance[:field2]).to eq 'Label Two'
+      end
+
+      it 'symbolize_keys returns a plain Hash' do
+        expect(instance.symbolize_keys).to eq(field1: 'Label One', field2: 'Label Two')
+      end
+    end
+
+    context 'DialogBefore creates NamedConfiguration for valid entries' do
+      before do
+        create_admin
+        Admin::MessageTemplate.create!(
+          name: 'test_dialog',
+          message_type: :dialog,
+          template_type: :content,
+          template: '<p>test</p>',
+          current_admin: @admin
+        )
+      end
+
+      let(:instance) { OptionConfigs::ExtraOptionConfigs::DialogBefore.new(field1: 'test_dialog') }
+
+      it 'converts string to NamedConfiguration with name attribute' do
+        nc = instance[:field1]
+        expect(nc).to be_a OptionConfigs::BaseNamedConfiguration
+        expect(nc[:name]).to eq 'test_dialog'
+      end
+
+      it 'reports warning for missing template' do
+        instance = OptionConfigs::ExtraOptionConfigs::DialogBefore.new(field1: 'nonexistent')
+        expect(instance.config_warnings).not_to be_empty
+      end
+    end
+
+    context 'ShowIf stores arbitrary condition hashes directly' do
+      let(:instance) { OptionConfigs::ExtraOptionConfigs::ShowIf.new(field1: { other_field: 'value' }) }
+
+      it 'returns condition hashes via bracket access' do
+        expect(instance[:field1]).to eq(other_field: 'value')
+      end
+
+      it 'symbolize_keys returns plain Hash of condition hashes' do
+        expect(instance.symbolize_keys).to eq(field1: { other_field: 'value' })
+      end
+    end
+
+    context 'FieldOptions preprocesses alt_options arrays' do
+      let(:instance) do
+        OptionConfigs::ExtraOptionConfigs::FieldOptions.new(
+          field1: { edit_as: { alt_options: %w[ChoiceA ChoiceB] } }
+        )
+      end
+
+      it 'converts alt_options Array to Hash' do
+        ao = instance[:field1][:edit_as][:alt_options]
+        expect(ao).to be_a Hash
+        expect(ao[:ChoiceA]).to eq 'choicea'
+      end
+    end
+
+    context 'DbConfigs stores column configs directly' do
+      let(:instance) { OptionConfigs::ExtraOptionConfigs::DbConfigs.new(col1: 'type_a') }
+
+      it 'returns values and symbolize_keys produces plain Hash' do
+        expect(instance[:col1]).to eq 'type_a'
+        expect(instance.symbolize_keys).to eq(col1: 'type_a')
+      end
+    end
+
+    context 'PresetFields stores preset values directly' do
+      let(:instance) { OptionConfigs::ExtraOptionConfigs::PresetFields.new(field1: 'default_val') }
+
+      it 'returns values via bracket access' do
+        expect(instance[:field1]).to eq 'default_val'
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ExtraOptions integration: config_instances
+  # ──────────────────────────────────────────────────────────────
+  describe 'ExtraOptions integration' do
+    it 'stores config_instances after initialization (empty since all converted to BaseConfiguration)' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Integration Test
+          fields:
+            - test1
+      YAML
+
+      expect(eo).to respond_to(:config_instances)
+      expect(eo.config_instances).to be_a Hash
+      # All classes are now BaseConfiguration — config_instances should be empty
+      expect(eo.config_instances).to be_empty
+    end
+
+    it 'no ConfigBase classes remain — config_instances is empty' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Full Config
+          fields:
+            - test1
+      YAML
+
+      expect(eo.config_instances).to be_empty
+
+      # Field-keyed classes should NOT be in config_instances
+      FIELD_KEYED_CLASSES.each do |class_name|
+        key = class_name.to_s.underscore.to_sym
+        expect(eo.config_instances).not_to have_key(key),
+                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
+      end
+
+      # Typed/direct config classes should NOT be in config_instances (stored directly as BaseConfiguration attribute)
+      TYPED_CONFIG_CLASSES.each do |class_name|
+        key = EXPECTED_CONFIG_CLASSES.key(class_name)
+        expect(eo.config_instances).not_to have_key(key),
+                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
+      end
+    end
+
+    it 'caption_before is stored directly as a CaptionBefore instance on ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Direct storage test
+      YAML
+
+      expect(eo.caption_before).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
+      expect(eo.caption_before[:test1]).to be_present
+    end
+
+    it 'field-keyed classes are stored directly as BaseConfiguration instances' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          labels:
+            test1: Test Label
+          show_if:
+            test1:
+              other_field: val
+          field_options:
+            test1:
+              no_downcase: true
+          db_configs:
+            test1: some_value
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      expect(eo.labels).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.show_if).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.field_options).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.db_configs).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.preset_fields).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'BaseConfiguration attribute values are accessible on ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Matching Test
+          fields:
+            - test1
+            - test2
+          labels:
+            test1: Test One
+          view_options:
+            data_attribute: test1
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      # Label and Fields use store_processed_value?, so stored as plain string/array
+      expect(eo.label).to eq 'Matching Test'
+      expect(eo.fields).to eq %w[test1 test2]
+      # Field-keyed classes are stored directly (not in config_instances)
+      expect(eo.labels[:test1]).to eq 'Test One'
+      # ViewOptions is a BaseConfiguration instance (not store_processed_value?)
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options[:data_attribute]).to eq 'test1'
+      expect(eo.preset_fields[:test1]).to eq 'preset_val'
+    end
+
+    it 'access_if classes store processed hash values (via store_processed_value?)' do
+      eo = config_for(<<~YAML)
+        default:
+          creatable_if:
+            always: true
+          editable_if:
+            never: true
+          showable_if:
+            user_is_creator: true
+      YAML
+
+      # store_processed_value? means the raw hash is stored, not the BaseConfiguration object
+      expect(eo.creatable_if).to be_a Hash
+      expect(eo.creatable_if[:always]).to eq true
+      expect(eo.editable_if).to be_a Hash
+      expect(eo.editable_if[:never]).to eq true
+      expect(eo.showable_if).to be_a Hash
+      expect(eo.showable_if[:user_is_creator]).to eq true
+    end
+
+    it 'caption_before values match between CaptionBefore instance and ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Simple caption text
+      YAML
+
+      cb = eo.caption_before
+      expect(cb).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
+      expect(cb[:test1][:caption]).to be_present
+    end
+
+    it 'save_trigger is stored directly as a SaveTrigger instance' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger[:on_create]).to be_a Array
+    end
+
+    it 'valid_if is stored directly as a ValidIf BaseConfiguration instance' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+      YAML
+
+      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
+      expect(eo.valid_if[:on_create]).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # config_obj mutation is properly handled outside config classes
+  # ──────────────────────────────────────────────────────────────
+  describe 'config_obj mutation handling' do
+    it 'sets config_obj.db_columns from db_configs after DbConfigs runs' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column: some_value
+      YAML
+
+      # db_columns should be set on the config_obj (DynamicModel)
+      expect(@dm.db_columns).to eq(some_column: 'some_value')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ActiveModel::Validations integration (run_validations bridge)
+  # ──────────────────────────────────────────────────────────────
+  # Tests for the run_validations bridge that calls valid? after
+  # setup_named_configurations and bridges ActiveModel::Validations
+  # errors into config_errors via failed_config. Also tests the
+  # TypedAttributeValidator custom validator that checks typed
+  # attributes have the correct type.
+  # ──────────────────────────────────────────────────────────────
+  describe 'ActiveModel::Validations integration' do
+    it 'errors is ActiveModel::Errors, not a plain Array' do
+      instance = OptionConfigs::ExtraOptionConfigs::BaseConfiguration.new({})
+      expect(instance.errors).to be_a(ActiveModel::Errors)
+    end
+
+    it 'validates declarations produce config_errors when value is blank' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_direct :test_attr, type: :string
+        validates :test_attr, presence: true
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).not_to be_empty
+      messages = instance.config_errors.map { |e| e[:message] }
+      expect(messages.join(' ')).to match(/test_attr.*blank|can't be blank/i)
+    end
+
+    it 'valid config produces no config_errors from validates' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_direct :test_attr, type: :string
+        validates :test_attr, presence: true
+
+        def setup_named_configurations
+          self.test_attr = 'a valid value'
+        end
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).to be_empty
+    end
+
+    it 'TypedAttributeValidator catches wrong type' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          setup_all_options_typed(hash_configuration)
+        end
+      end
+
+      instance = test_class.new({})
+      # Manually assign wrong type after initialization
+      instance.my_typed = 'wrong'
+      instance.valid?
+      expect(instance.errors[:my_typed]).not_to be_empty
+      expect(instance.errors[:my_typed].join(' ')).to match(/must be a.*TriggerTasks.*got String/)
+    end
+
+    it 'TypedAttributeValidator passes correct type' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          setup_all_options_typed(hash_configuration)
+        end
+      end
+
+      instance = test_class.new(my_typed: { notify: { type: 'email' } })
+      expect(instance.my_typed).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.valid?).to be true
+      expect(instance.errors[:my_typed]).to be_empty
+    end
+
+    it 'TypedAttributeValidator allows nil' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          # Don't set my_typed — leave it nil
+        end
+      end
+
+      instance = test_class.new({})
+      expect(instance.my_typed).to be_nil
+      expect(instance.valid?).to be true
+      expect(instance.errors[:my_typed]).to be_empty
+    end
+
+    it 'full integration: BatchTrigger subclass with validates produces config_errors on empty config' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BatchTrigger) do
+        validates :on_record, presence: true
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).not_to be_empty
+      messages = instance.config_errors.map { |e| e[:message] }
+      expect(messages.join(' ')).to match(/on_record.*blank|can't be blank/i)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # validate callbacks (migrated from manual failed_config calls)
+  # ──────────────────────────────────────────────────────────────
+  # Phase 3 of issue #986: Verify that validation logic in ValidIf,
+  # SaveTrigger, and SetVariable subclasses produces the expected
+  # config_errors and ActiveModel::Errors when given invalid input.
+  # Tests 1-7 verify config_errors (pass now, pass after migration).
+  # Tests 8-10 verify ActiveModel errors (FAIL now, pass after migration).
+  describe 'validate callbacks' do
+    describe 'ValidIf' do
+      it 'with invalid keys has errors on :valid_if' do
+        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_invalid_key: { always: true })
+        expect(instance.config_errors).not_to be_empty
+        err = instance.config_errors.find { |e| e[:type] == :valid_if }
+        expect(err).to be_present
+        expect(err[:message]).to match(/invalid keys/)
+      end
+
+      it 'with valid keys has no validation errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_save: { all: { this: { field: 'is not null' } } })
+        expect(instance.config_errors).to be_empty
+      end
+
+      it 'with invalid keys has ActiveModel errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_invalid_key: { always: true })
+        expect(instance.errors[:valid_if]).not_to be_empty
+      end
+    end
+
+    describe 'SaveTrigger' do
+      it 'with invalid keys has errors on :save_trigger' do
+        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_invalid_trigger: { something: true })
+        expect(instance.config_errors).not_to be_empty
+        err = instance.config_errors.find { |e| e[:type] == :save_trigger }
+        expect(err).to be_present
+        expect(err[:message]).to match(/invalid keys/)
+      end
+
+      it 'with valid keys has no validation errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_create: [{ notify: { type: 'email' } }])
+        expect(instance.config_errors).to be_empty
+      end
+
+      it 'with invalid keys has ActiveModel errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_invalid_trigger: { something: true })
+        expect(instance.errors[:save_trigger]).not_to be_empty
+      end
+    end
+
+    describe 'SetVariable' do
+      it 'with non-array input has errors on :set_variables' do
+        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new({ name: 'var1', value: 'val1' })
+        expect(instance.config_errors).not_to be_empty
+        err = instance.config_errors.find { |e| e[:type] == :set_variables }
+        expect(err).to be_present
+        expect(err[:message]).to match(/must be an array/)
+      end
+
+      it 'with invalid entries has errors on :set_variables' do
+        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new([{ bad_key: 'test' }])
+        expect(instance.config_errors).not_to be_empty
+        err = instance.config_errors.find { |e| e[:type] == :set_variables }
+        expect(err).to be_present
+        expect(err[:message]).to match(/must have 'name' and 'value' keys/)
+      end
+
+      it 'with valid entries has no validation errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new([{ name: 'v', value: 'x' }])
+        expect(instance.config_errors).to be_empty
+      end
+
+      it 'with non-array has ActiveModel errors' do
+        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new({ name: 'var1', value: 'val1' })
+        expect(instance.errors[:set_variables]).not_to be_empty
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # References.reprocess (#986)
+  # Verify that References.reprocess can re-run prepare_config on an
+  # already-initialized ExtraOptions instance after its references
+  # attribute has been mutated. This method does not exist yet and
+  # these tests are expected to FAIL in the red phase.
+  # ──────────────────────────────────────────────────────────────
+  describe 'References.reprocess' do
+    let(:references_class) { OptionConfigs::ExtraOptionConfigs::References }
+
+    it 'exists as a class method on References' do
+      expect(references_class).to respond_to(:reprocess)
+    end
+
+    it 're-processes references after post-initialization mutation' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          references:
+            player_contact:
+              from: this
+              add: many
+      YAML
+      eo = config_for(yaml)
+
+      # Initial references should have been processed (singular key, metadata populated)
+      expect(eo.references).to be_a(Hash)
+      initial_ref = eo.references[:player_contact]
+      expect(initial_ref).to be_present
+      expect(initial_ref[:player_contact][:to_record_label]).to be_present
+
+      # Mutate references with a raw hash using plural keys (simulating post-init mutation)
+      eo.references = { player_contacts: { from: 'this', add: 'many' } }
+
+      # Call reprocess to re-run prepare_config on the mutated value
+      references_class.reprocess(eo)
+
+      # After reprocessing, plural keys should be singularized
+      expect(eo.references).to be_a(Hash)
+      reprocessed_ref = eo.references[:player_contact]
+      expect(reprocessed_ref).to be_present, 'Expected plural key :player_contacts to be singularized to :player_contact'
+      expect(reprocessed_ref[:player_contact][:to_record_label]).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Old clean_ methods removed (#986)
+  # Confirm that the 21 legacy clean_ methods have been removed from
+  # ExtraOptions. They were replaced by config_class_registry classes.
+  # ──────────────────────────────────────────────────────────────
+  describe 'old clean_ methods removed' do
+    let(:removed_clean_methods) do
+      %i[
+        clean_label_def
+        clean_caption_before_def
+        clean_dialog_before_def
+        clean_labels_def
+        clean_show_if_def
+        clean_save_action_def
+        clean_view_options_def
+        clean_db_configs_def
+        clean_fields_def
+        clean_field_options_def
+        clean_filestore_def
+        clean_access_if_def
+        clean_valid_if_def
+        clean_embed_def
+        clean_references_def
+        clean_save_triggers
+        clean_batch_triggers
+        clean_config_triggers
+        clean_preset_fields
+        clean_set_variables_def
+        clean_field_configs
+      ]
+    end
+
+    it 'no longer defines any clean_ instance methods' do
+      removed_clean_methods.each do |method_name|
+        expect(OptionConfigs::ExtraOptions.method_defined?(method_name, false))
+          .to be(false), "Expected #{method_name} to be removed from ExtraOptions"
+      end
+    end
+
+    it 'still initializes correctly without clean_ methods' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          caption_before:
+            test_field: A Caption
+          show_if:
+            test_field:
+              test_field2: value
+          view_options:
+            show_result_options: true
+      YAML
+      eo = config_for(yaml)
+      expect(eo.label).to eq('Test')
+      expect(eo.caption_before).to be_present
+      expect(eo.show_if).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Validate callbacks for remaining classes (#986)
+  #
+  # RED PHASE: These tests verify that DialogBefore, Embed,
+  # References, and FieldConfigs use ActiveModel validate callbacks
+  # (errors.add) instead of calling failed_config directly.
+  #
+  # Currently these classes report errors via failed_config in
+  # prepare_config or add_named_configuration. After migration,
+  # they should populate ActiveModel errors on the INSTANCE,
+  # which run_validations bridges into config_errors.
+  #
+  # These tests WILL FAIL until the production code is migrated.
+  # ──────────────────────────────────────────────────────────────
+  describe 'validate callbacks for remaining classes (#986)' do
+    describe 'DialogBefore' do
+      let(:klass) { OptionConfigs::ExtraOptionConfigs::DialogBefore }
+
+      it 'produces ActiveModel errors when value is an invalid type' do
+        # 12345 is neither String nor Hash — should be rejected
+        instance = klass.new(test_field: 12_345)
+        expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
+                                                                              'Expected ActiveModel error on :dialog_before for invalid type, but none found'
+      end
+
+      it 'produces ActiveModel errors (warning level) when template does not exist' do
+        instance = klass.new(test_field: { name: 'nonexistent_template_xyz_999' })
+        # After migration, missing template should produce an ActiveModel error on :dialog_before
+        expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
+                                                                              'Expected ActiveModel error on :dialog_before for missing template, but none found'
+      end
+
+      it 'has no ActiveModel errors when given valid configuration' do
+        # Create a real message template so the validation passes
+        Admin::MessageTemplate.create!(
+          name: 'test_dialog_template_986',
+          message_type: :dialog,
+          template_type: :content,
+          template: '<p>Test</p>',
+          current_admin: @admin
+        )
+        instance = klass.new(test_field: { name: 'test_dialog_template_986' })
+        expect(instance.errors).to be_empty,
+                                   "Expected no ActiveModel errors for valid dialog_before, got: #{instance.errors.full_messages}"
+      end
+    end
+
+    describe 'Embed' do
+      let(:klass) { OptionConfigs::ExtraOptionConfigs::Embed }
+
+      it 'produces ActiveModel errors on the instance when resource does not exist' do
+        # Simulate what the registry does: call prepare_config then create instance
+        yaml = <<~YAML
+          default:
+            label: Test
+            embed: nonexistent_resource_xyz_999
+        YAML
+        eo = config_for(yaml)
+
+        # Re-create the instance directly to check ActiveModel errors on INSTANCE
+        processed = klass.prepare_config('nonexistent_resource_xyz_999', eo)
+        instance = klass.new(processed)
+        expect(instance.errors.any? { |e| e.attribute == :embed }).to be(true),
+                                                                      'Expected ActiveModel error on :embed for non-existent resource, but none found on instance'
+      end
+
+      it 'has no ActiveModel errors on the instance when embed is valid' do
+        # Use proper plural resource name that Resources::Models recognizes
+        yaml = <<~YAML
+          default:
+            label: Test
+            embed: player_contacts
+        YAML
+        eo = config_for(yaml)
+
+        processed = klass.prepare_config('player_contacts', eo)
+        instance = klass.new(processed)
+        expect(instance.errors).to be_empty,
+                                   "Expected no ActiveModel errors for valid embed, got: #{instance.errors.full_messages}"
+      end
+    end
+
+    describe 'References' do
+      let(:klass) { OptionConfigs::ExtraOptionConfigs::References }
+
+      it 'produces ActiveModel errors on the instance when reference class does not exist' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            references:
+              nonexistent_model_xyz_999:
+                from: this
+                add: many
+        YAML
+        eo = config_for(yaml)
+
+        raw = { nonexistent_model_xyz_999: { from: 'this', add: 'many' } }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors.any? { |e| e.attribute == :references }).to be(true),
+                                                                           'Expected ActiveModel error on :references for non-existent class, but none found on instance'
+      end
+
+      it 'has no ActiveModel errors on the instance when references are valid' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            references:
+              player_contact:
+                from: this
+                add: many
+        YAML
+        eo = config_for(yaml)
+
+        raw = { player_contact: { from: 'this', add: 'many' } }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors).to be_empty,
+                                   "Expected no ActiveModel errors for valid references, got: #{instance.errors.full_messages}"
+      end
+    end
+
+    describe 'FieldConfigs' do
+      let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldConfigs }
+
+      it 'produces ActiveModel errors when a field value is not a Hash' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            fields:
+              - test_field
+            field_configs:
+              test_field: not_a_hash
+        YAML
+        eo = config_for(yaml)
+
+        raw = { test_field: 'not_a_hash' }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                              'Expected ActiveModel error on :field_configs for non-Hash field value, but none found on instance'
+      end
+
+      it 'produces ActiveModel errors when fields are not in the field list' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            fields:
+              - test_field
+            field_configs:
+              unknown_field:
+                caption_before: Test Caption
+        YAML
+        eo = config_for(yaml)
+
+        raw = { unknown_field: { caption_before: 'Test Caption' } }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                              'Expected ActiveModel error on :field_configs for field not in field list, but none found on instance'
+      end
+
+      it 'produces ActiveModel errors when field_configs contain invalid keys' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            fields:
+              - test_field
+            field_configs:
+              test_field:
+                totally_invalid_key: some_value
+        YAML
+        eo = config_for(yaml)
+
+        raw = { test_field: { totally_invalid_key: 'some_value' } }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                              'Expected ActiveModel error on :field_configs for invalid keys, but none found on instance'
+      end
+
+      it 'has no ActiveModel errors when field_configs are valid' do
+        yaml = <<~YAML
+          default:
+            label: Test
+            fields:
+              - test_field
+            field_configs:
+              test_field:
+                caption_before: A Caption
+        YAML
+        eo = config_for(yaml)
+
+        raw = { test_field: { caption_before: 'A Caption' } }
+        processed = klass.prepare_config(raw, eo)
+        instance = klass.new(processed)
+        expect(instance.errors).to be_empty,
+                                   "Expected no ActiveModel errors for valid field_configs, got: #{instance.errors.full_messages}"
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # NfsStoreConfig (issue #986 – migrated from ActivityLogOptions#clean_nfs_store_def)
+  # Validates nfs_store keys and delegates pipeline cleaning to NfsStore::Config::ExtraOptions.clean_def
+  # ──────────────────────────────────────────────────────────────
+  describe 'NfsStoreConfig' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::NfsStoreConfig }
+
+    it 'exists and inherits from BaseConfiguration' do
+      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'stores processed value' do
+      expect(klass.store_processed_value?).to be true
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:nfs_store)
+    end
+
+    it 'produces ActiveModel errors for invalid top-level nfs_store keys' do
+      raw = { always_use_this_for_access_control: true, invalid_key_xyz: 'bad' }
+      instance = klass.new(raw)
+      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
+                                                                        'Expected ActiveModel error on :nfs_store for invalid top-level keys'
+    end
+
+    it 'produces ActiveModel errors for invalid can sub-keys' do
+      raw = { can: { download_if: true, bogus_permission: 'bad' } }
+      instance = klass.new(raw)
+      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
+                                                                        'Expected ActiveModel error on :nfs_store for invalid can sub-keys'
+    end
+
+    it 'has no ActiveModel errors when all keys are valid' do
+      raw = { always_use_this_for_access_control: true, can: { download_if: true } }
+      instance = klass.new(raw)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid nfs_store keys, got: #{instance.errors.full_messages}"
+    end
+
+    it 'has no ActiveModel errors when nfs_store is nil' do
+      instance = klass.new(nil)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for nil nfs_store, got: #{instance.errors.full_messages}"
+    end
+
+    it 'delegates pipeline cleaning via prepare_config' do
+      raw = { pipeline: [], user_file_actions: [] }
+      expect(NfsStore::Config::ExtraOptions).to receive(:clean_def).with(raw)
+      klass.prepare_config(raw, nil)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ESignConfig (issue #986 – migrated from ActivityLogOptions#clean_e_sign_def)
+  # Transforms e_sign document_reference structure: wraps in {item: ...},
+  # singularizes keys, and resolves model references.
+  # ──────────────────────────────────────────────────────────────
+  describe 'ESignConfig' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::ESignConfig }
+
+    it 'exists and inherits from BaseConfiguration' do
+      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'stores processed value' do
+      expect(klass.store_processed_value?).to be true
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:e_sign)
+    end
+
+    it 'wraps document_reference in {item: ...} if not already wrapped' do
+      raw = { document_reference: { player_contacts: { label: 'Contact' } } }
+      result = klass.prepare_config(raw, nil)
+      expect(result[:document_reference]).to have_key(:item),
+                                             'Expected document_reference to be wrapped in {item: ...}'
+    end
+
+    it 'does not double-wrap document_reference that already has :item key' do
+      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
+      result = klass.prepare_config(raw, nil)
+      expect(result[:document_reference][:item]).not_to have_key(:item),
+                                                        'Expected document_reference not to be double-wrapped'
+    end
+
+    it 'singularizes keys within each reference item' do
+      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
+      result = klass.prepare_config(raw, nil)
+      item = result[:document_reference][:item]
+      expect(item).to have_key(:player_contact),
+                      'Expected pluralized key :player_contacts to be singularized to :player_contact'
+      expect(item).not_to have_key(:player_contacts),
+                          'Expected original pluralized key :player_contacts to be removed after singularization'
+    end
+
+    it 'resolves model references with to_record_label, no_master_association, to_model_name_us' do
+      raw = { document_reference: { item: { player_contacts: { label: 'My Label' } } } }
+      result = klass.prepare_config(raw, nil)
+      ref = result[:document_reference][:item][:player_contact]
+      expect(ref).to have_key(:to_record_label),
+                     'Expected :to_record_label to be set on resolved reference'
+      expect(ref).to have_key(:to_model_name_us),
+                     'Expected :to_model_name_us to be set on resolved reference'
+    end
+
+    it 'returns nil from prepare_config when raw is nil' do
+      result = klass.prepare_config(nil, nil)
+      expect(result).to be_nil
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ActivityLogOptions config_class_registry integration (issue #986)
+  # After migration, nfs_store and e_sign should be registered config classes
+  # and the old clean_ instance methods should no longer exist.
+  # ──────────────────────────────────────────────────────────────
+  describe 'ActivityLogOptions config_class_registry' do
+    it 'extends parent registry with nfs_store' do
+      registry = OptionConfigs::ActivityLogOptions.config_class_registry
+      expect(registry).to have_key(:nfs_store),
+                          'Expected ActivityLogOptions.config_class_registry to include :nfs_store'
+    end
+
+    it 'extends parent registry with e_sign' do
+      registry = OptionConfigs::ActivityLogOptions.config_class_registry
+      expect(registry).to have_key(:e_sign),
+                          'Expected ActivityLogOptions.config_class_registry to include :e_sign'
+    end
+
+    it 'maps nfs_store to NfsStoreConfig class' do
+      registry = OptionConfigs::ActivityLogOptions.config_class_registry
+      expect(registry[:nfs_store]).to eq(OptionConfigs::ExtraOptionConfigs::NfsStoreConfig)
+    end
+
+    it 'maps e_sign to ESignConfig class' do
+      registry = OptionConfigs::ActivityLogOptions.config_class_registry
+      expect(registry[:e_sign]).to eq(OptionConfigs::ExtraOptionConfigs::ESignConfig)
+    end
+
+    it 'returns empty add_key_attributes' do
+      expect(OptionConfigs::ActivityLogOptions.add_key_attributes).to eq([])
+    end
+
+    it 'does not define clean_nfs_store_def as instance method' do
+      expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_nfs_store_def, false)).to be false
+    end
+
+    it 'does not define clean_e_sign_def as instance method' do
+      expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_e_sign_def, false)).to be false
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_options_clean_methods_spec.rb b/spec/models/option_configs/extra_options_clean_methods_spec.rb
new file mode 100644
index 0000000000..786a0d9daf
--- /dev/null
+++ b/spec/models/option_configs/extra_options_clean_methods_spec.rb
@@ -0,0 +1,1196 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Phase 1 of issue #986: Capture the current behavior of each ExtraOptions `clean_...` method
+# with explicit tests. These tests document the exact output format produced by each method
+# given known inputs, establishing a safety net for the Phase 2 refactoring into
+# dedicated configuration classes.
+#
+# Each describe block covers one `clean_...` method. Tests verify:
+# - Default initialization when no config is provided
+# - Correct transformation of valid input
+# - Edge cases: nil inputs, empty hashes, invalid keys, nested structures
+#
+# The test strategy instantiates ExtraOptions through the standard parse path
+# (DynamicModel#option_configs) so that the full initialization sequence runs,
+# including inter-method dependencies.
+RSpec.describe 'ExtraOptions clean methods', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  # Helper: update the DynamicModel with given YAML options and return the first option config
+  def config_for(yaml)
+    @dm.update!(options: yaml, current_admin: @admin)
+    @dm.option_configs.first
+  end
+
+  # Helper: return all option configs for the given YAML
+  def all_configs_for(yaml)
+    @dm.update!(options: yaml, current_admin: @admin)
+    @dm.option_configs
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_fields_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_fields_def' do
+    it 'defaults fields to an empty array when not specified in options' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No fields
+      YAML
+      # When no fields are specified in options, fields defaults to []
+      # (the DynamicModel may have its own field_list but clean_fields_def
+      # only sets [] if fields is nil in the options config)
+      expect(eo.fields).to be_an Array
+    end
+
+    it 'preserves a provided field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+      YAML
+      expect(eo.fields).to eq %w[test1 test2]
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_label_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_label_def' do
+    it 'defaults label to a humanized version of the config name' do
+      eo = config_for(<<~YAML)
+        my_custom_name:
+          fields:
+            - test1
+      YAML
+      expect(eo.label).to eq 'My custom name'
+    end
+
+    it 'preserves an explicitly set label' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Custom Label
+      YAML
+      expect(eo.label).to eq 'Custom Label'
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_caption_before_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_caption_before_def' do
+    it 'defaults caption_before to a blank CaptionBefore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No captions
+      YAML
+      expect(eo.caption_before).to be_blank
+    end
+
+    it 'converts a plain string caption to a hash with all caption modes' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Simple caption text
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb).to respond_to(:[])
+      expect(cb[:caption]).to be_present
+      expect(cb[:edit_caption]).to be_present
+      expect(cb[:show_caption]).to be_present
+      expect(cb[:new_caption]).to be_present
+      # All modes should have the same HTML-converted value
+      expect(cb[:caption]).to eq cb[:edit_caption]
+      expect(cb[:caption]).to eq cb[:show_caption]
+      expect(cb[:caption]).to eq cb[:new_caption]
+    end
+
+    it 'converts text to HTML via Formatter::Substitution.text_to_html' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: "Line one\\nLine two"
+      YAML
+
+      cb = eo.caption_before[:test1]
+      # The text_to_html conversion should produce HTML content
+      expect(cb[:caption]).to be_a String
+      expect(cb[:caption]).not_to be_empty
+    end
+
+    it 'preserves hash-style caption_before with individual mode values' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1:
+              caption: Show and edit caption
+              edit_caption: Edit only caption
+              show_caption: Show only caption
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:caption]).to include('Show and edit caption')
+      expect(cb[:edit_caption]).to include('Edit only caption')
+      expect(cb[:show_caption]).to include('Show only caption')
+    end
+
+    it 'defaults new_caption to edit_caption when not explicitly set' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1:
+              edit_caption: Edit caption value
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:new_caption]).to eq cb[:edit_caption]
+    end
+
+    it 'symbolizes caption_before keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: A caption
+      YAML
+
+      expect(eo.caption_before.keys.first).to be_a Symbol
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_dialog_before_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_dialog_before_def' do
+    it 'defaults dialog_before to a blank DialogBefore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No dialogs
+      YAML
+      expect(eo.dialog_before).to be_blank
+    end
+
+    it 'converts a string value to a hash with name key' do
+      # Create a message template first, so the warning is not generated
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog_template',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1: test_dialog_template
+      YAML
+
+      db = eo.dialog_before[:test1]
+      expect(db).to respond_to(:[]) # NamedConfiguration with bracket access
+      expect(db[:name]).to eq 'test_dialog_template'
+    end
+
+    it 'preserves a hash value with name key' do
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog_hash',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1:
+              name: test_dialog_hash
+      YAML
+
+      db = eo.dialog_before[:test1]
+      expect(db[:name]).to eq 'test_dialog_hash'
+    end
+
+    it 'reports a warning when the named message template does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1: nonexistent_template
+      YAML
+
+      expect(eo.config_warnings).not_to be_empty
+      warn_msg = eo.config_warnings.find { |w| w[:type] == :dialog_before }
+      expect(warn_msg).to be_present
+    end
+
+    it 'reports an error when the value is not a String or Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1:
+              - invalid_array_item
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :dialog_before }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes dialog_before keys' do
+      Admin::MessageTemplate.create!(
+        name: 'dialog_sym_test',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          dialog_before:
+            test1: dialog_sym_test
+      YAML
+
+      expect(eo.dialog_before.keys.first).to be_a Symbol
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_labels_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_labels_def' do
+    it 'defaults labels to a blank Labels instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No labels
+      YAML
+      expect(eo.labels).to be_blank
+    end
+
+    it 'preserves explicitly set labels and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          labels:
+            test1: Test One
+            test2: Test Two
+      YAML
+
+      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_show_if_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_show_if_def' do
+    it 'defaults show_if to a blank ShowIf instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No show_if
+      YAML
+      expect(eo.show_if).to be_blank
+    end
+
+    it 'preserves explicitly set show_if conditions and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          show_if:
+            test2:
+              test1: some_value
+      YAML
+
+      expect(eo.show_if).to have_key(:test2)
+      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
+    end
+
+    it 'does not overwrite existing show_if when show_if_condition_strings provides a duplicate' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          show_if:
+            test2:
+              test1: existing_value
+          show_if_condition_strings:
+            test2: "[test1] = 'other_value'"
+      YAML
+
+      # The existing show_if should take priority
+      expect(eo.show_if[:test2]).to eq(test1: 'existing_value')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_save_action_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_save_action_def' do
+    it 'defaults save_action to a blank SaveAction when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No save action
+      YAML
+      expect(eo.save_action).to be_a OptionConfigs::ExtraOptionConfigs::SaveAction
+      expect(eo.save_action).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Saved
+      YAML
+
+      expect(eo.save_action.save_action[:on_save]).to eq(label: 'Saved')
+      expect(eo.save_action.save_action[:on_create]).to eq(label: 'Saved')
+      expect(eo.save_action.save_action[:on_update]).to eq(label: 'Saved')
+    end
+
+    it 'merges on_save into existing on_create and on_update without overwriting them' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Default
+              notify: true
+            on_create:
+              label: Created
+            on_update:
+              another_key: updated_val
+      YAML
+
+      expect(eo.save_action.save_action[:on_create][:label]).to eq 'Created'
+      expect(eo.save_action.save_action[:on_create][:notify]).to eq true
+      expect(eo.save_action.save_action[:on_update][:label]).to eq 'Default'
+      expect(eo.save_action.save_action[:on_update][:another_key]).to eq 'updated_val'
+    end
+
+    it 'symbolizes save_action keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Test
+      YAML
+      expect(eo.save_action.save_action.keys).to all(be_a Symbol)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_view_options_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_view_options_def' do
+    it 'defaults view_options to a blank ViewOptions when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No view options
+      YAML
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options).to be_blank
+    end
+
+    it 'preserves view_options and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          view_options:
+            data_attribute: field_1
+            show_embedded: true
+      YAML
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_db_configs_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_db_configs_def' do
+    it 'defaults db_configs to a blank DbConfigs instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No db configs
+      YAML
+      expect(eo.db_configs).to be_blank
+    end
+
+    it 'symbolizes db_configs keys' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column: some_value
+      YAML
+      expect(eo.db_configs.keys).to all(be_a Symbol)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_access_if_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_access_if_def' do
+    it 'defaults all access_if attributes to empty hashes' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No access
+      YAML
+
+      expect(eo.creatable_if).to eq({})
+      expect(eo.editable_if).to eq({})
+      expect(eo.showable_if).to eq({})
+    end
+
+    it 'preserves and symbolizes creatable_if, editable_if, showable_if' do
+      eo = config_for(<<~YAML)
+        default:
+          creatable_if:
+            always: true
+          editable_if:
+            never: true
+          showable_if:
+            user_is_creator: true
+      YAML
+
+      expect(eo.creatable_if).to eq(always: true)
+      expect(eo.editable_if).to eq(never: true)
+      expect(eo.showable_if).to eq(user_is_creator: true)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_valid_if_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_valid_if_def' do
+    it 'defaults valid_if to a blank ValidIf when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No valid_if
+      YAML
+      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
+      expect(eo.valid_if).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+      YAML
+
+      expect(eo.valid_if.valid_if[:on_save]).to be_present
+      expect(eo.valid_if.valid_if[:on_create]).to eq eo.valid_if.valid_if[:on_save]
+      expect(eo.valid_if.valid_if[:on_update]).to eq eo.valid_if.valid_if[:on_save]
+    end
+
+    it 'merges on_save into existing on_create and on_update' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+            on_create:
+              all:
+                this:
+                  test2: is not null
+      YAML
+
+      expect(eo.valid_if.valid_if[:on_create]).to have_key(:all)
+    end
+
+    it 'reports an error for invalid trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_invalid_key:
+              always: true
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :valid_if }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes valid_if keys' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              always: true
+      YAML
+      expect(eo.valid_if.valid_if.keys).to all(be_a Symbol)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_filestore_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_filestore_def' do
+    it 'defaults filestore to a blank Filestore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No filestore
+      YAML
+      expect(eo.filestore).to be_a OptionConfigs::ExtraOptionConfigs::Filestore
+      expect(eo.filestore).to be_blank
+    end
+
+    it 'preserves and symbolizes filestore keys' do
+      eo = config_for(<<~YAML)
+        default:
+          filestore:
+            always_use_this_for_access_control: true
+      YAML
+      expect(eo.filestore.symbolize_keys).to eq(always_use_this_for_access_control: true)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_field_options_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_field_options_def' do
+    it 'defaults field_options to a blank FieldOptions instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No field options
+      YAML
+      expect(eo.field_options).to be_blank
+    end
+
+    it 'preserves field_options and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              no_downcase: true
+      YAML
+      expect(eo.field_options[:test1]).to eq(no_downcase: true)
+    end
+
+    it 'converts edit_as.alt_options from Array to Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              edit_as:
+                field_type: select
+                alt_options:
+                  - Choice A
+                  - Choice B
+      YAML
+
+      ao = eo.field_options[:test1][:edit_as][:alt_options]
+      expect(ao).to be_a Hash
+      # Array items are converted: key is symbolized, value is downcased string
+      expect(ao[:'Choice A']).to eq 'choice a'
+      expect(ao[:'Choice B']).to eq 'choice b'
+    end
+
+    it 'preserves edit_as.alt_options when already a Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              edit_as:
+                field_type: select
+                alt_options:
+                  'Option 1': opt1
+                  'Option 2': opt2
+      YAML
+
+      ao = eo.field_options[:test1][:edit_as][:alt_options]
+      expect(ao).to be_a Hash
+      expect(ao[:'Option 1']).to eq 'opt1'
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_embed_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_embed_def' do
+    it 'leaves embed as nil when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No embed
+      YAML
+      expect(eo.embed).to be_nil
+    end
+
+    it 'converts a string resource_name into a hash with resource_name key' do
+      # The referenced resource likely won't exist, but the structure should be set
+      eo = config_for(<<~YAML)
+        default:
+          embed: dynamic_model__some_resource
+      YAML
+
+      expect(eo.embed).to be_a Hash
+      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
+    end
+
+    it 'preserves a hash-style embed with resource_name' do
+      eo = config_for(<<~YAML)
+        default:
+          embed:
+            resource_name: dynamic_model__some_resource
+      YAML
+
+      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
+    end
+
+    it 'warns when the embedded resource does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          embed:
+            resource_name: dynamic_model__nonexistent_model
+      YAML
+
+      expect(eo.config_warnings).not_to be_empty
+      warn = eo.config_warnings.find { |w| w[:type] == :embed }
+      expect(warn).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_references_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_references_def' do
+    it 'leaves references as nil when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No references
+      YAML
+      expect(eo.references).to be_nil
+    end
+
+    it 'converts a hash-style references, singularizing keys' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            player_infos:
+              label: Player Info Ref
+      YAML
+
+      # Keys should be singularized
+      expect(eo.references).to be_a Hash
+      ref_keys = eo.references.keys
+      # The key should wrap the reference as { singular_key => config }
+      ref_keys.each do |k|
+        inner = eo.references[k]
+        expect(inner).to be_a Hash
+      end
+    end
+
+    it 'converts an array-style references to a hash' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            - player_infos:
+                label: Player Info Ref
+      YAML
+
+      expect(eo.references).to be_a Hash
+    end
+
+    it 'warns when a referenced model does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            nonexistent_model_xyz:
+              label: Bad Reference
+      YAML
+
+      # Should generate a warning (not an error, since order of imports may cause this)
+      has_warning = eo.config_warnings.any? { |w| w[:type] == :references }
+      # May also just silently skip if to_class is nil; check references is cleaned up
+      expect(eo.references).to be_a Hash
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_save_triggers
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_save_triggers' do
+    it 'defaults save_trigger to a SaveTrigger with blank TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No save triggers
+      YAML
+
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger[:on_upload]).to be_a Hash
+      expect(eo.save_trigger[:on_upload]).to be_blank
+      expect(eo.save_trigger[:on_disable]).to be_a Hash
+      expect(eo.save_trigger[:on_disable]).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as array defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+
+      expect(eo.save_trigger[:on_create]).to be_an Array
+      expect(eo.save_trigger[:on_update]).to be_an Array
+      expect(eo.save_trigger[:on_create].length).to eq 1
+      expect(eo.save_trigger[:on_update].length).to eq 1
+    end
+
+    it 'appends on_save triggers to existing on_create and on_update' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+            on_create:
+              create_action:
+                type: special
+      YAML
+
+      # on_create should have both on_save and its own trigger
+      expect(eo.save_trigger[:on_create]).to be_an Array
+      expect(eo.save_trigger[:on_create].length).to eq 2
+      # on_update should only have on_save trigger
+      expect(eo.save_trigger[:on_update]).to be_an Array
+      expect(eo.save_trigger[:on_update].length).to eq 1
+    end
+
+    it 'reports an error for invalid trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_invalid_trigger:
+              something: true
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :save_trigger }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes save_trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger.on_create).to be_a OptionConfigs::ExtraOptionConfigs::TriggerTasks
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_batch_triggers
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_batch_triggers' do
+    it 'defaults batch_trigger to a BatchTrigger with blank on_record TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No batch triggers
+      YAML
+
+      expect(eo.batch_trigger).to be_a OptionConfigs::ExtraOptionConfigs::BatchTrigger
+      expect(eo.batch_trigger[:on_record]).to be_a Hash
+      expect(eo.batch_trigger[:on_record]).to be_blank
+    end
+
+    it 'preserves batch_trigger configuration and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          batch_trigger:
+            on_record:
+              action: process
+      YAML
+
+      expect(eo.batch_trigger[:on_record]).to be_a Hash
+      expect(eo.batch_trigger[:on_record]).to eq(action: 'process')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_config_triggers
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_config_triggers' do
+    it 'defaults config_trigger to a ConfigTrigger with empty on_define TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No config triggers
+      YAML
+
+      expect(eo.config_trigger).to be_a OptionConfigs::ExtraOptionConfigs::ConfigTrigger
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define]).to be_blank
+    end
+
+    it 'wraps on_define in an array if it is not already an array' do
+      eo = config_for(<<~YAML)
+        default:
+          config_trigger:
+            on_define:
+              action: do_something
+      YAML
+
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define].length).to eq 1
+    end
+
+    it 'preserves on_define as an array if already provided' do
+      eo = config_for(<<~YAML)
+        default:
+          config_trigger:
+            on_define:
+              - action: first
+              - action: second
+      YAML
+
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define].length).to eq 2
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_preset_fields
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_preset_fields' do
+    it 'defaults preset_fields to a blank PresetFields instance' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No presets
+      YAML
+      expect(eo.preset_fields).to be_blank
+    end
+
+    it 'preserves and symbolizes preset_fields' do
+      eo = config_for(<<~YAML)
+        default:
+          preset_fields:
+            test1: default_value
+            test2: another_value
+      YAML
+      expect(eo.preset_fields.symbolize_keys).to eq(test1: 'default_value', test2: 'another_value')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_set_variables_def
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_set_variables_def' do
+    it 'defaults set_variables to a blank SetVariable when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No variables
+      YAML
+      expect(eo.set_variables).to be_nil
+    end
+
+    it 'preserves valid set_variables array entries' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            - name: var1
+              value: val1
+            - name: var2
+              value: val2
+              if:
+                always: true
+      YAML
+
+      expect(eo.set_variables).to be_an Array
+      expect(eo.set_variables.length).to eq 2
+      expect(eo.set_variables[0][:name]).to eq 'var1'
+      expect(eo.set_variables[0][:value]).to eq 'val1'
+      expect(eo.set_variables[1][:name]).to eq 'var2'
+      expect(eo.set_variables[1][:if]).to be_present
+    end
+
+    it 'reports an error and empties when set_variables is not an array' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            name: var1
+            value: val1
+      YAML
+
+      expect(eo.set_variables).to eq []
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :set_variables }
+      expect(err).to be_present
+    end
+
+    it 'filters out invalid entries missing name or value keys' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            - name: valid_var
+              value: valid_val
+            - no_name_key: invalid
+      YAML
+
+      expect(eo.set_variables).to be_an Array
+      expect(eo.set_variables.length).to eq 1
+      expect(eo.set_variables[0][:name]).to eq 'valid_var'
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # clean_field_configs
+  # ──────────────────────────────────────────────────────────────
+  describe '#clean_field_configs' do
+    it 'defaults field_configs to an empty hash when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No field configs
+      YAML
+      expect(eo.field_configs).to eq({})
+    end
+
+    it 'merges field_configs into the standalone configs (caption_before, labels, etc.)' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          field_configs:
+            test1:
+              caption_before: Caption for test1
+              labels: Label for test1
+            test2:
+              show_if:
+                test1: some_value
+      YAML
+
+      # field_configs should merge caption_before into the standalone caption_before
+      expect(eo.caption_before[:test1]).to be_present
+      # field_configs should merge labels into standalone labels
+      expect(eo.labels[:test1]).to eq 'Label for test1'
+      # field_configs should merge show_if into standalone show_if
+      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
+    end
+
+    it 'reports an error when field_configs references fields not in the field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            nonexistent_field:
+              labels: Some label
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'reports an error when field_configs contains invalid config keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1:
+              invalid_key: some value
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'reports an error when a field config value is not a Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1: not_a_hash
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'stores raw_field_configs as a deep clone before standalone defs are merged' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1:
+              labels: Raw label
+          labels:
+            test1: Standalone label
+      YAML
+
+      # raw_field_configs should be a deep copy of field_configs before standalone merge
+      expect(eo.raw_field_configs).to be_a Hash
+      expect(eo.raw_field_configs[:test1]).to be_a Hash
+      # Modifying raw_field_configs should not affect field_configs
+      original_fc = eo.field_configs[:test1].dup
+      eo.raw_field_configs[:test1][:labels] = 'Modified'
+      expect(eo.field_configs[:test1]).to eq original_fc
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # add_field_configs_from_standalone_defs
+  # ──────────────────────────────────────────────────────────────
+  describe '#add_field_configs_from_standalone_defs' do
+    it 'merges standalone configs back into field_configs for valid fields' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          labels:
+            test1: Standalone Label 1
+          caption_before:
+            test2: Standalone caption
+      YAML
+
+      expect(eo.field_configs[:test1]).to include(labels: 'Standalone Label 1')
+      expect(eo.field_configs[:test2]).to be_a Hash
+      expect(eo.field_configs[:test2]).to have_key(:caption_before)
+    end
+
+    it 'does not include standalone configs for fields not in the field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          labels:
+            test1: Included
+            not_a_field: Excluded
+      YAML
+
+      expect(eo.field_configs).not_to have_key(:not_a_field)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # resource_name and resource_item_name initialization
+  # ──────────────────────────────────────────────────────────────
+  describe 'resource_name initialization' do
+    it 'sets resource_name from config_obj and option name' do
+      eo = config_for(<<~YAML)
+        my_option:
+          label: Test
+      YAML
+
+      expect(eo.resource_name).to include('my_option')
+      expect(eo.resource_item_name).to eq eo.resource_name
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Integration: full initialization sequence
+  # ──────────────────────────────────────────────────────────────
+  describe 'full initialization with multiple configs' do
+    it 'initializes all clean_ methods in sequence without errors for valid config' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          label: Full Test
+          labels:
+            test1: Test One
+            test2: Test Two
+          caption_before:
+            test1: Caption One
+          view_options:
+            data_attribute: test1
+          save_action:
+            on_save:
+              label: Saved
+          field_options:
+            test1:
+              no_downcase: true
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      expect(eo.config_errors).to be_empty
+      expect(eo.label).to eq 'Full Test'
+      expect(eo.fields).to eq %w[test1 test2]
+      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
+      expect(eo.caption_before[:test1]).to respond_to(:[])
+      expect(eo.caption_before[:test1][:caption]).to be_present
+      expect(eo.view_options[:data_attribute]).to eq 'test1'
+      expect(eo.save_action[:on_create][:label]).to eq 'Saved'
+      expect(eo.field_options[:test1][:no_downcase]).to eq true
+      expect(eo.preset_fields[:test1]).to eq 'preset_val'
+    end
+
+    it 'handles multiple named option configs from a single definition' do
+      configs = all_configs_for(<<~YAML)
+        option_a:
+          label: Option A
+          fields:
+            - test1
+        option_b:
+          label: Option B
+          fields:
+            - test2
+      YAML
+
+      # parse_config may produce additional configs from _comments processing
+      # but our named configs should be present
+      names = configs.map(&:name)
+      expect(names).to include(:option_a)
+      expect(names).to include(:option_b)
+      expect(configs.length).to be >= 2
+    end
+  end
+end
diff --git a/spec/models/save_triggers/notify_spec.rb b/spec/models/save_triggers/notify_spec.rb
index 0344792198..667bd9ef35 100644
--- a/spec/models/save_triggers/notify_spec.rb
+++ b/spec/models/save_triggers/notify_spec.rb
@@ -118,7 +118,7 @@
       }
     }
 
-    @al.extra_log_type_config.clean_references_def
+    OptionConfigs::ExtraOptionConfigs::References.reprocess(@al.extra_log_type_config)
     @al.extra_log_type_config.editable_if = { always: true }
 
     setup_access @al.class.resource_name, resource_type: :table, access: :create, user: @user
diff --git a/spec/support/activity_log_support.rb b/spec/support/activity_log_support.rb
index 0cc1f4a7aa..9794399044 100644
--- a/spec/support/activity_log_support.rb
+++ b/spec/support/activity_log_support.rb
@@ -15,7 +15,7 @@ def gen_activity_log_path(master_id, item_id, id = nil)
   # e.g add_reference_def_to(activity_log, [player_contacts: { from: 'this', add: 'many' }])
   def add_reference_def_to(activity_log, ref_def)
     activity_log.option_type_config.references = ref_def
-    activity_log.option_type_config.clean_references_def
+    OptionConfigs::ExtraOptionConfigs::References.reprocess(activity_log.option_type_config)
   end
 
   def generate_test_activity_log

From 462badcbbeb0e99b085de98b9f2124a52320b2c5 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 02/16] Added source_attribute pattern, ReferenceEntry
 NamedConfiguration, split specs into per-class files - resolves #986

---
 .../base_configuration.rb                     |    9 +
 .../extra_option_configs/references.rb        |  208 +-
 app/models/option_configs/extra_options.rb    |   25 +-
 .../activity_log_options_spec.rb              |   57 +
 .../batch_trigger_spec.rb                     |   89 +
 .../caption_before_spec.rb                    |  292 +++
 .../config_trigger_spec.rb                    |  110 +
 .../extra_option_configs/db_configs_spec.rb   |   62 +
 .../dialog_before_spec.rb                     |  177 ++
 .../e_sign_config_spec.rb                     |   80 +
 .../extra_option_configs/embed_spec.rb        |  128 +
 .../field_configs_spec.rb                     |  251 ++
 .../field_options_spec.rb                     |   97 +
 .../extra_option_configs/fields_spec.rb       |   76 +
 .../extra_option_configs/filestore_spec.rb    |   76 +
 .../extra_option_configs/if_condition_spec.rb |  173 ++
 .../extra_option_configs/integration_spec.rb  |  293 +++
 .../extra_option_configs/label_spec.rb        |   83 +
 .../extra_option_configs/labels_spec.rb       |   59 +
 .../nfs_store_config_spec.rb                  |   76 +
 .../preset_fields_spec.rb                     |   52 +
 .../extra_option_configs/references_spec.rb   |  283 +++
 .../extra_option_configs/registry_spec.rb     |  236 ++
 .../extra_option_configs/save_action_spec.rb  |  116 +
 .../extra_option_configs/save_trigger_spec.rb |  203 ++
 .../extra_option_configs/set_variable_spec.rb |  150 ++
 .../extra_option_configs/show_if_spec.rb      |   78 +
 .../trigger_tasks_spec.rb                     |   78 +
 .../extra_option_configs/valid_if_spec.rb     |  165 ++
 .../extra_option_configs/validations_spec.rb  |  117 +
 .../extra_option_configs/view_options_spec.rb |   78 +
 .../extra_option_configs_spec.rb              | 2099 -----------------
 .../extra_options_clean_methods_spec.rb       | 1196 ----------
 spec/support/extra_option_configs_support.rb  |   59 +
 34 files changed, 3942 insertions(+), 3389 deletions(-)
 create mode 100644 spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/batch_trigger_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/caption_before_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/config_trigger_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/db_configs_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/dialog_before_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/embed_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/field_configs_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/field_options_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/fields_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/filestore_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/if_condition_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/integration_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/label_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/labels_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/nfs_store_config_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/preset_fields_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/references_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/registry_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/save_action_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/set_variable_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/show_if_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/trigger_tasks_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/valid_if_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/validations_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/view_options_spec.rb
 delete mode 100644 spec/models/option_configs/extra_option_configs_spec.rb
 delete mode 100644 spec/models/option_configs/extra_options_clean_methods_spec.rb
 create mode 100644 spec/support/extra_option_configs_support.rb

diff --git a/app/models/option_configs/extra_option_configs/base_configuration.rb b/app/models/option_configs/extra_option_configs/base_configuration.rb
index 00ebf47223..e7f231a0e5 100644
--- a/app/models/option_configs/extra_option_configs/base_configuration.rb
+++ b/app/models/option_configs/extra_option_configs/base_configuration.rb
@@ -35,6 +35,15 @@ def self.store_processed_value?
         false
       end
 
+      # Optional: override to read raw input from a different ExtraOptions attribute
+      # than the registry key. For example, References uses `source_attribute :references`
+      # so the registry key `references_config` reads its input from `extra_options.references`,
+      # and the enriched hash is stored back there while the instance is kept at the registry key.
+      # @return [Symbol, nil] the source attribute name, or nil to use the registry key
+      def self.source_attribute
+        nil
+      end
+
       # Initialize with just a hash config (no owner required).
       # Bypasses the parent's owner-based initialization since these
       # config classes don't persist independently — managed by ExtraOptions.
diff --git a/app/models/option_configs/extra_option_configs/references.rb b/app/models/option_configs/extra_option_configs/references.rb
index fe04b3a7ce..1c33ae2fb3 100644
--- a/app/models/option_configs/extra_option_configs/references.rb
+++ b/app/models/option_configs/extra_option_configs/references.rb
@@ -3,18 +3,45 @@
 module OptionConfigs
   module ExtraOptionConfigs
     # Configuration class for model reference configurations.
-    # Converted from ConfigBase to BaseConfiguration pattern.
+    #
+    # Uses the source_attribute pattern: the registry key is :references_config,
+    # but the raw input is read from :references (a base_key_attribute).
+    # After processing:
+    # - extra_options.references = enriched hash (views/models consume this)
+    # - extra_options.references_config = this References instance (configurations hold ReferenceEntry objects)
     #
     # Handles:
     # - Converting array-style and hash-style references
     # - Singularizing reference keys
     # - Looking up target classes and enriching reference metadata
     # - Warning when referenced models do not exist
-    #
-    # The processed hash is stored back on the parent ExtraOptions (not the object).
     class References < BaseConfiguration
       configure_direct :references, type: :hash
 
+      # Keys added by enrich_ref_metadata that are not part of admin input.
+      COMPUTED_KEYS = %i[
+        to_record_label no_master_association to_model_name_us
+        to_model_class_name to_table_name to_schema_name to_class_type
+      ].freeze
+
+      # Named configuration for a single reference entry's admin-configured attributes.
+      # Validates that only recognized keys are present in each reference config.
+      class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
+        configure_attributes %i[
+          label result_label from without_reference add add_with
+          filter_by order_by limit type_config
+          view_as view_options showable_if creatable_if
+          prevent_disable also_disable_record allow_disable_if_not_editable
+          prevent_reload_on_save action_position
+        ]
+      end
+
+      ReferenceEntry = NamedConfiguration
+
+      def self.source_attribute
+        :references
+      end
+
       def self.store_processed_value?
         true
       end
@@ -22,67 +49,78 @@ def self.store_processed_value?
       validate :validate_references
 
       # Pre-process references using parent context.
-      # Converts array/hash formats, singularizes keys, looks up target classes.
+      # Normalizes array/hash formats, singularizes keys, resolves target classes,
+      # and enriches reference entries with class metadata.
       # @param raw [Array, Hash, nil] the raw references value from YAML config
       # @param parent [ExtraOptions] the parent ExtraOptions instance
       # @return [Hash, nil] the processed references hash
       def self.prepare_config(raw, parent)
         return nil unless raw
 
-        config_obj = parent.config_obj
-        new_ref = {}
-
-        if raw.is_a? Array
-          raw.each do |refitem|
-            # Make all keys singular, to simplify configurations
-            add_refitem = {}
-            refitem.each do |k, _v|
-              if k.to_s != k.to_s.singularize
-                new_k = k.to_s.singularize.to_sym
-                add_refitem[new_k] = refitem.delete(k)
-              end
-            end
-
-            refitem.merge! add_refitem
-
-            refitem.each do |k, v|
-              vi = v[:add_with] && v[:add_with][:extra_log_type]
-              ckey = k.to_s
-              ckey += "_#{vi}" if vi
-              new_ref[ckey.to_sym] = { k => v }
-            end
-          end
-        else
-          refs = raw.dup
-          fix_refs = {}
+        new_ref = normalize_references(raw)
+        bad_items = resolve_reference_classes(new_ref, parent)
+        new_ref[:_bad_references] = bad_items if bad_items.present?
+        new_ref
+      end
 
-          # Make all keys singular, to simplify configurations
-          refs.each do |k, _v|
-            fix_refs[k] = refs[k] if k.to_s != k.to_s.singularize
+      # Normalize raw references from Array or Hash format into a unified hash.
+      # Each entry maps a composite key to { model_name => config }.
+      # Plural keys are singularized (e.g. :player_contacts => :player_contact).
+      # @param raw [Array, Hash] raw references from YAML config
+      # @return [Hash] normalized references hash
+      private_class_method def self.normalize_references(raw)
+        ref_items = raw.is_a?(Array) ? raw.map(&:dup) : [raw.dup]
+
+        result = {}
+        ref_items.each do |refitem|
+          singularize_keys!(refitem)
+          refitem.each do |k, v|
+            result[composite_ref_key(k, v)] = { k => v }
           end
+        end
+        result
+      end
 
-          fix_refs.each do |k, _v|
-            new_k = k.to_s.singularize.to_sym
-            refs[new_k] = refs.delete(k)
-          end
+      # Replace all plural keys with their singular form, mutating the hash.
+      # @param hash [Hash] hash whose keys to singularize
+      # @return [void]
+      private_class_method def self.singularize_keys!(hash)
+        hash.keys.each do |k|
+          singular = k.to_s.singularize.to_sym
+          next if singular == k
 
-          refs.each do |k, v|
-            vi = v[:add_with] && v[:add_with][:extra_log_type]
-            ckey = k.to_s
-            ckey += "_#{vi}" if vi
-            new_ref[ckey.to_sym] = { k => v }
-          end
+          hash[singular] = hash.delete(k)
         end
+      end
 
+      # Build a composite reference key from the model name and optional extra_log_type.
+      # For example, :player_contact or :player_contact_initial_review.
+      # @param model_name [Symbol] the singularized model name
+      # @param config [Hash] the reference configuration
+      # @return [Symbol] composite key
+      private_class_method def self.composite_ref_key(model_name, config)
+        elt = config.dig(:add_with, :extra_log_type)
+        key = model_name.to_s
+        key += "_#{elt}" if elt
+        key.to_sym
+      end
+
+      # Resolve target classes for each reference and enrich with metadata.
+      # Removes entries whose classes cannot be resolved.
+      # @param new_ref [Hash] normalized references hash (mutated in place)
+      # @param parent [ExtraOptions] the parent ExtraOptions instance (used for log context)
+      # @return [Array<Symbol>] model names that could not be resolved
+      private_class_method def self.resolve_reference_classes(new_ref, parent)
         all_bad_items = []
-        bad_items = []
-        new_ref.each do |_k, refitem|
-          bad_items.clear
+
+        new_ref.each_value do |refitem|
+          bad_items = []
+
           refitem.each do |mn, conf|
             to_class = ModelReference.to_record_class_for_type(mn)
 
-            # Avoid breaking app type imports if the resource being pointed to in the reference
-            # hasn't been set up yet.
+            # Skip references whose target model or definition isn't set up yet,
+            # to avoid breaking app type imports.
             if to_class.nil? || (to_class.respond_to?(:definition) && !to_class.definition)
               Rails.logger.warn "Definition for class #{to_class} is not set - skipping reference setup for #{mn}"
               all_bad_items << mn
@@ -90,48 +128,37 @@ def self.prepare_config(raw, parent)
               break
             end
 
-            if to_class
-              elt = conf[:add_with] && conf[:add_with][:extra_log_type]
-              add_with_elt = nil
-              add_with_elt = to_class.human_name_for(elt) if elt && to_class.respond_to?(:human_name_for)
-              refitem[mn][:to_record_label] = conf[:result_label] || conf[:label] || add_with_elt || to_class.human_name
-
-              if to_class.respond_to?(:no_master_association)
-                refitem[mn][:no_master_association] = to_class.no_master_association
-              end
-
-              refitem[mn][:to_model_name_us] = to_class.to_s&.ns_underscore
-              refitem[mn][:to_model_class_name] = to_class.to_s
-              refitem[mn][:to_table_name] = to_class.table_name
-              nil
-
-              if to_class.respond_to?(:definition)
-                cd = to_class.definition
-                tsn = cd.schema_name
-                tct = cd.class.to_s
-                refitem[mn][:to_schema_name] = tsn
-                refitem[mn][:to_class_type] = tct
-              end
-            else
-              bad_items << mn
-              all_bad_items << mn
-              Rails.logger.warn "extra log type reference for #{mn} does not exist as a class in #{parent.name} / #{config_obj.name}"
-              Rails.logger.info 'Will clean up reference to avoid it being used again in this session'
-            end
+            enrich_ref_metadata(refitem, mn, conf, to_class)
           end
 
-          # Cleanup bad items
-          bad_items.each do |br|
-            refitem.delete(br)
-          end
+          bad_items.each { |br| refitem.delete(br) }
         end
 
-        # Store bad_ref_items on parent for backward compatibility
-        parent.bad_ref_items = bad_items
-
-        new_ref[:_bad_references] = all_bad_items if all_bad_items.present?
+        all_bad_items
+      end
 
-        new_ref
+      # Enrich a single reference entry with resolved class metadata.
+      # @param refitem [Hash] the reference item hash (mutated)
+      # @param model_name [Symbol] the model name key
+      # @param conf [Hash] the reference configuration
+      # @param to_class [Class] the resolved target class
+      # @return [void]
+      private_class_method def self.enrich_ref_metadata(refitem, model_name, conf, to_class)
+        elt = conf.dig(:add_with, :extra_log_type)
+        add_with_label = to_class.human_name_for(elt) if elt && to_class.respond_to?(:human_name_for)
+
+        entry = refitem[model_name]
+        entry[:to_record_label] = conf[:result_label] || conf[:label] || add_with_label || to_class.human_name
+        entry[:no_master_association] = to_class.no_master_association if to_class.respond_to?(:no_master_association)
+        entry[:to_model_name_us] = to_class.to_s.ns_underscore
+        entry[:to_model_class_name] = to_class.to_s
+        entry[:to_table_name] = to_class.table_name
+
+        return unless to_class.respond_to?(:definition)
+
+        defn = to_class.definition
+        entry[:to_schema_name] = defn.schema_name
+        entry[:to_class_type] = defn.class.to_s
       end
 
       # Re-process references on an already-initialized ExtraOptions instance.
@@ -142,10 +169,19 @@ def self.reprocess(instance)
         instance.references = prepare_config(instance.references, instance)
       end
 
-      # Store the references hash value.
+      # Store the enriched hash on the direct attribute and create ReferenceEntry
+      # named configurations for each entry's input-only keys.
       # @return [void]
       def setup_named_configurations
         self.references = hash_configuration.except(:_bad_references).presence
+        return unless references
+
+        references.each do |composite_key, refitem|
+          refitem.each_value do |config|
+            input_only = config.except(*COMPUTED_KEYS)
+            add_named_configuration(composite_key, input_only)
+          end
+        end
       end
 
       private
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index b58dfa0832..4ea6801d38 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -35,7 +35,7 @@ def self.config_class_registry
         filestore: ExtraOptionConfigs::Filestore,
         field_options: ExtraOptionConfigs::FieldOptions,
         embed: ExtraOptionConfigs::Embed,
-        references: ExtraOptionConfigs::References,
+        references_config: ExtraOptionConfigs::References,
         save_trigger: ExtraOptionConfigs::SaveTrigger,
         batch_trigger: ExtraOptionConfigs::BatchTrigger,
         config_trigger: ExtraOptionConfigs::ConfigTrigger,
@@ -48,6 +48,7 @@ def self.base_key_attributes
       %i[
         name config_obj resource_name resource_item_name add_reference_if
         button_label orig_config show_if_condition_strings raw_field_configs
+        references
       ]
     end
 
@@ -67,7 +68,7 @@ def self.editable_attributes
       key_attributes - %i[name config_obj resource_name resource_item_name] + [:label]
     end
 
-    attr_accessor(*key_attributes, :def_item, :bad_ref_items, :config_instances)
+    attr_accessor(*key_attributes, :def_item, :config_instances)
 
     #
     # Initialize a named option configuration, which may form one of many in a dynamic definition
@@ -99,15 +100,20 @@ def initialize(name, config, config_obj)
         # Delegate to configuration classes in order
         self.class.config_class_registry.each do |key, config_class|
           if config_class < ExtraOptionConfigs::BaseConfiguration
-            # BaseConfiguration config: initialize with raw value
-            raw = send(key)
+            # Determine where to read raw input (source_attribute or registry key)
+            source_key = config_class.source_attribute || key
+            raw = send(source_key)
             raw = config_class.prepare_config(raw, self) if config_class.respond_to?(:prepare_config)
             instance = config_class.new(raw)
 
-            # Collect errors/warnings before potentially discarding the instance
-            collect_instance_errors(instance)
-
-            if config_class.store_processed_value?
+            if config_class.source_attribute
+              # source_attribute pattern: enriched value → source attr, instance → registry key
+              direct_attr = config_class.option_types[:direct]&.first || source_key
+              send("#{source_key}=", instance.send(direct_attr))
+              send("#{key}=", instance)
+            elsif config_class.store_processed_value?
+              # Collect errors/warnings before discarding the instance
+              collect_instance_errors(instance)
               # Value-preprocessor class: store the processed value, not the object
               direct_attr = config_class.option_types[:direct]&.first || key
               send("#{key}=", instance.send(direct_attr))
@@ -188,6 +194,9 @@ def collect_instance_errors(instance)
     # Collect config errors and warnings from field-keyed config instances
     # (those inheriting ExtraOptionConfigs::BaseConfiguration) into the
     # parent ExtraOptions config_errors/config_warnings arrays.
+    # Only collects from instances that were not already collected via
+    # collect_instance_errors during initialization (i.e. store_processed_value?
+    # classes that were discarded).
     def collect_field_config_errors
       self.class.config_class_registry.each do |key, config_class|
         next unless config_class < ExtraOptionConfigs::BaseConfiguration
diff --git a/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb b/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
new file mode 100644
index 0000000000..c23510d265
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ActivityLogOptions config_class_registry integration.
+# Verifies that nfs_store and e_sign are registered config classes
+# and the old clean_ instance methods no longer exist.
+RSpec.describe 'ActivityLogOptions config_class_registry', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  it 'extends parent registry with nfs_store' do
+    registry = OptionConfigs::ActivityLogOptions.config_class_registry
+    expect(registry).to have_key(:nfs_store),
+                        'Expected ActivityLogOptions.config_class_registry to include :nfs_store'
+  end
+
+  it 'extends parent registry with e_sign' do
+    registry = OptionConfigs::ActivityLogOptions.config_class_registry
+    expect(registry).to have_key(:e_sign),
+                        'Expected ActivityLogOptions.config_class_registry to include :e_sign'
+  end
+
+  it 'maps nfs_store to NfsStoreConfig class' do
+    registry = OptionConfigs::ActivityLogOptions.config_class_registry
+    expect(registry[:nfs_store]).to eq(OptionConfigs::ExtraOptionConfigs::NfsStoreConfig)
+  end
+
+  it 'maps e_sign to ESignConfig class' do
+    registry = OptionConfigs::ActivityLogOptions.config_class_registry
+    expect(registry[:e_sign]).to eq(OptionConfigs::ExtraOptionConfigs::ESignConfig)
+  end
+
+  it 'returns empty add_key_attributes' do
+    expect(OptionConfigs::ActivityLogOptions.add_key_attributes).to eq([])
+  end
+
+  it 'does not define clean_nfs_store_def as instance method' do
+    expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_nfs_store_def, false)).to be false
+  end
+
+  it 'does not define clean_e_sign_def as instance method' do
+    expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_e_sign_def, false)).to be false
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/batch_trigger_spec.rb b/spec/models/option_configs/extra_option_configs/batch_trigger_spec.rb
new file mode 100644
index 0000000000..457c92786b
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/batch_trigger_spec.rb
@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for BatchTrigger configuration class.
+# Verifies BaseConfiguration inheritance, TriggerTasks typed attributes,
+# and integration through ExtraOptions initialization (clean_batch_triggers behavior).
+RSpec.describe 'ExtraOptionConfigs::BatchTrigger', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::BatchTrigger }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares on_record as a typed attribute with TriggerTasks type' do
+      expect(klass.option_types[:typed]).to include(:on_record)
+      expect(klass.typed_attribute_types[:on_record]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+    end
+  end
+
+  describe 'initialization' do
+    it 'initializes on_record as a TriggerTasks instance from hash' do
+      instance = klass.new(on_record: { notify: { type: 'email' } })
+      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_record.tasks).to eq(notify: { type: 'email' })
+    end
+
+    it 'initializes on_record as blank TriggerTasks when not provided' do
+      instance = klass.new({})
+      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_record).to be_blank
+    end
+
+    it 'supports hash-like bracket access for on_record' do
+      instance = klass.new(on_record: { action: 'process' })
+      expect(instance[:on_record]).to be_a(Hash)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults batch_trigger to a BatchTrigger with blank on_record TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No batch triggers
+      YAML
+
+      expect(eo.batch_trigger).to be_a OptionConfigs::ExtraOptionConfigs::BatchTrigger
+      expect(eo.batch_trigger[:on_record]).to be_a Hash
+      expect(eo.batch_trigger[:on_record]).to be_blank
+    end
+
+    it 'preserves batch_trigger configuration and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          batch_trigger:
+            on_record:
+              action: process
+      YAML
+
+      expect(eo.batch_trigger[:on_record]).to be_a Hash
+      expect(eo.batch_trigger[:on_record]).to eq(action: 'process')
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/caption_before_spec.rb b/spec/models/option_configs/extra_option_configs/caption_before_spec.rb
new file mode 100644
index 0000000000..96fda145c8
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/caption_before_spec.rb
@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for CaptionBefore configuration class.
+# Verifies the BaseConfiguration/NamedConfiguration pattern, hash-like interface,
+# JSON serialization, unrecognized attribute warnings, and integration through
+# ExtraOptions initialization (clean_caption_before_def behavior).
+RSpec.describe 'ExtraOptionConfigs::CaptionBefore', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::CaptionBefore }
+
+  describe 'class structure' do
+    it 'inherits from BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::BaseConfiguration)
+    end
+
+    it 'defines a NamedConfiguration inner class' do
+      expect(klass.const_defined?(:NamedConfiguration)).to be true
+    end
+
+    it 'NamedConfiguration inherits from BaseNamedConfiguration' do
+      expect(klass::NamedConfiguration.ancestors).to include(OptionConfigs::BaseNamedConfiguration)
+    end
+
+    it 'NamedConfiguration declares caption attributes via configure_attributes' do
+      expected = %i[caption edit_caption show_caption new_caption]
+      expected.each do |attr|
+        expect(klass::NamedConfiguration.option_types[:simple]).to include(attr)
+      end
+    end
+  end
+
+  context 'initialized with a raw hash' do
+    let(:raw_config) { { test1: 'Simple text', test2: { caption: 'Cap', edit_caption: 'Edit' } } }
+    let(:instance) { klass.new(raw_config) }
+
+    it 'creates named configurations for each field' do
+      expect(instance.configurations).to have_key(:test1)
+      expect(instance.configurations).to have_key(:test2)
+    end
+
+    it 'stores NamedConfiguration objects in configurations' do
+      expect(instance.configurations[:test1]).to be_a klass::NamedConfiguration
+      expect(instance.configurations[:test2]).to be_a klass::NamedConfiguration
+    end
+
+    it 'preprocesses string values into all caption modes' do
+      nc = instance.configurations[:test1]
+      expect(nc.caption).to be_present
+      expect(nc.edit_caption).to eq nc.caption
+      expect(nc.show_caption).to eq nc.caption
+      expect(nc.new_caption).to eq nc.caption
+    end
+
+    it 'preserves hash values with individual mode settings' do
+      nc = instance.configurations[:test2]
+      expect(nc.caption).to include('Cap')
+      expect(nc.edit_caption).to include('Edit')
+    end
+
+    it 'defaults new_caption to edit_caption when not specified' do
+      nc = instance.configurations[:test2]
+      expect(nc.new_caption).to eq nc.edit_caption
+    end
+  end
+
+  context 'hash-like interface' do
+    let(:raw_config) { { test1: 'Caption text' } }
+    let(:instance) { klass.new(raw_config) }
+
+    it '[] returns a NamedConfiguration for a given field' do
+      expect(instance[:test1]).to be_a klass::NamedConfiguration
+    end
+
+    it '[] returns nil for missing fields' do
+      expect(instance[:nonexistent]).to be_nil
+    end
+
+    it 'NamedConfiguration supports [] for attribute access' do
+      nc = instance[:test1]
+      expect(nc[:caption]).to eq nc.caption
+      expect(nc[:edit_caption]).to eq nc.edit_caption
+    end
+
+    it 'supports keys method' do
+      expect(instance.keys).to eq [:test1]
+    end
+
+    it 'supports each iteration' do
+      yielded = []
+      instance.each { |k, v| yielded << [k, v.class] }
+      expect(yielded).to eq [[:test1, klass::NamedConfiguration]]
+    end
+
+    it 'supports blank? for empty config' do
+      empty = klass.new({})
+      expect(empty).to be_blank
+    end
+
+    it 'supports blank? for populated config' do
+      expect(instance).not_to be_blank
+    end
+
+    it 'supports merge! with a plain hash' do
+      instance.merge!(test2: { caption: 'New cap' })
+      expect(instance[:test2]).to be_a klass::NamedConfiguration
+      expect(instance[:test2].caption).to include('New cap')
+    end
+
+    it 'supports []= assignment' do
+      instance[:test3] = { caption: 'Assigned' }
+      expect(instance[:test3]).to be_a klass::NamedConfiguration
+      expect(instance[:test3].caption).to include('Assigned')
+    end
+
+    it 'symbolize_keys returns a plain Hash for backward compat' do
+      result = instance.symbolize_keys
+      expect(result).to be_a Hash
+      expect(result[:test1]).to be_a Hash
+      expect(result[:test1]).to have_key(:caption)
+    end
+  end
+
+  context 'JSON serialization' do
+    let(:raw_config) { { test1: 'Cap text', test2: { caption: 'C', edit_caption: 'E' } } }
+    let(:instance) { klass.new(raw_config) }
+
+    it 'as_json returns a plain nested hash' do
+      json = instance.as_json
+      expect(json).to be_a Hash
+      expect(json['test1']).to be_a Hash
+      expect(json['test1']).to have_key('caption')
+    end
+
+    it 'to_json produces valid JSON matching the expected format' do
+      json_str = instance.to_json
+      parsed = JSON.parse(json_str)
+      expect(parsed).to have_key('test1')
+      expect(parsed['test1']).to have_key('caption')
+    end
+
+    it 'empty config serializes to empty JSON object' do
+      empty = klass.new({})
+      expect(JSON.parse(empty.to_json)).to eq({})
+    end
+  end
+
+  context 'unrecognized NamedConfiguration attributes' do
+    it 'reports a config warning when a field has an unrecognized attribute' do
+      raw = { test1: { caption: 'Valid', bogus_attr: 'Invalid' } }
+      instance = klass.new(raw)
+      expect(instance.config_warnings).to be_present,
+                                          'Expected config_warnings for unrecognized attribute bogus_attr'
+      warning_messages = instance.config_warnings.map { |w| w[:message] }
+      expect(warning_messages.any? { |m| m.include?('bogus_attr') }).to be(true),
+                                                                        "Expected warning mentioning 'bogus_attr', got: #{warning_messages}"
+    end
+
+    it 'does not report warnings for valid attributes only' do
+      raw = { test1: { caption: 'Cap', edit_caption: 'Edit', show_caption: 'Show', new_caption: 'New' } }
+      instance = klass.new(raw)
+      expect(instance.config_warnings).to be_empty,
+                                          "Expected no config_warnings for valid attributes, got: #{instance.config_warnings}"
+    end
+
+    it 'does not report warnings for string values (auto-expanded)' do
+      raw = { test1: 'Simple text' }
+      instance = klass.new(raw)
+      expect(instance.config_warnings).to be_empty,
+                                          "Expected no config_warnings for string value, got: #{instance.config_warnings}"
+    end
+
+    it 'reports multiple unrecognized attributes in a single field' do
+      raw = { test1: { caption: 'Valid', bad1: 'x', bad2: 'y' } }
+      instance = klass.new(raw)
+      warning_messages = instance.config_warnings.map { |w| w[:message] }
+      expect(warning_messages.any? { |m| m.include?('bad1') }).to be(true)
+      expect(warning_messages.any? { |m| m.include?('bad2') }).to be(true)
+    end
+
+    it 'reports unrecognized attributes across multiple fields' do
+      raw = { field1: { caption: 'OK', nope1: 'x' }, field2: { bogus2: 'y' } }
+      instance = klass.new(raw)
+      warning_messages = instance.config_warnings.map { |w| w[:message] }
+      expect(warning_messages.any? { |m| m.include?('nope1') }).to be(true)
+      expect(warning_messages.any? { |m| m.include?('bogus2') }).to be(true)
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults caption_before to a blank CaptionBefore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No captions
+      YAML
+      expect(eo.caption_before).to be_blank
+    end
+
+    it 'converts a plain string caption to a hash with all caption modes' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Simple caption text
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb).to respond_to(:[])
+      expect(cb[:caption]).to be_present
+      expect(cb[:edit_caption]).to be_present
+      expect(cb[:show_caption]).to be_present
+      expect(cb[:new_caption]).to be_present
+      expect(cb[:caption]).to eq cb[:edit_caption]
+      expect(cb[:caption]).to eq cb[:show_caption]
+      expect(cb[:caption]).to eq cb[:new_caption]
+    end
+
+    it 'converts text to HTML via Formatter::Substitution.text_to_html' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: "Line one\\nLine two"
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:caption]).to be_a String
+      expect(cb[:caption]).not_to be_empty
+    end
+
+    it 'preserves hash-style caption_before with individual mode values' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1:
+              caption: Show and edit caption
+              edit_caption: Edit only caption
+              show_caption: Show only caption
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:caption]).to include('Show and edit caption')
+      expect(cb[:edit_caption]).to include('Edit only caption')
+      expect(cb[:show_caption]).to include('Show only caption')
+    end
+
+    it 'defaults new_caption to edit_caption when not explicitly set' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1:
+              edit_caption: Edit caption value
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:new_caption]).to eq cb[:edit_caption]
+    end
+
+    it 'symbolizes caption_before keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: A caption
+      YAML
+
+      expect(eo.caption_before.keys.first).to be_a Symbol
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/config_trigger_spec.rb b/spec/models/option_configs/extra_option_configs/config_trigger_spec.rb
new file mode 100644
index 0000000000..7170fd4f80
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/config_trigger_spec.rb
@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ConfigTrigger configuration class.
+# Verifies BaseConfiguration inheritance, TriggerTasks typed attributes,
+# and integration through ExtraOptions initialization (clean_config_triggers behavior).
+RSpec.describe 'ExtraOptionConfigs::ConfigTrigger', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::ConfigTrigger }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares on_define as a typed attribute with TriggerTasks type' do
+      expect(klass.option_types[:typed]).to include(:on_define)
+      expect(klass.typed_attribute_types[:on_define]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+    end
+  end
+
+  describe 'initialization' do
+    it 'wraps non-array on_define in an array' do
+      instance = klass.new(on_define: { action: 'do_something' })
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define.tasks).to be_an Array
+      expect(instance.on_define.tasks.length).to eq 1
+    end
+
+    it 'preserves array on_define' do
+      instance = klass.new(on_define: [{ action: 'first' }, { action: 'second' }])
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define.tasks).to be_an Array
+      expect(instance.on_define.tasks.length).to eq 2
+    end
+
+    it 'defaults on_define to blank TriggerTasks when not provided' do
+      instance = klass.new({})
+      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_define).to be_blank
+    end
+
+    it 'supports hash-like bracket access' do
+      instance = klass.new(on_define: [{ action: 'test' }])
+      expect(instance[:on_define]).to be_a(Array)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults config_trigger to a ConfigTrigger with empty on_define TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No config triggers
+      YAML
+
+      expect(eo.config_trigger).to be_a OptionConfigs::ExtraOptionConfigs::ConfigTrigger
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define]).to be_blank
+    end
+
+    it 'wraps on_define in an array if it is not already an array' do
+      eo = config_for(<<~YAML)
+        default:
+          config_trigger:
+            on_define:
+              action: do_something
+      YAML
+
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define].length).to eq 1
+    end
+
+    it 'preserves on_define as an array if already provided' do
+      eo = config_for(<<~YAML)
+        default:
+          config_trigger:
+            on_define:
+              - action: first
+              - action: second
+      YAML
+
+      expect(eo.config_trigger[:on_define]).to be_an Array
+      expect(eo.config_trigger[:on_define].length).to eq 2
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/db_configs_spec.rb b/spec/models/option_configs/extra_option_configs/db_configs_spec.rb
new file mode 100644
index 0000000000..e516884af1
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/db_configs_spec.rb
@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for DbConfigs configuration class.
+# Verifies field-keyed BaseConfiguration behavior and integration through
+# ExtraOptions initialization (clean_db_configs_def behavior).
+RSpec.describe 'ExtraOptionConfigs::DbConfigs', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::DbConfigs }
+
+  describe 'initialization' do
+    it 'stores column configs directly' do
+      instance = klass.new(col1: 'type_a')
+      expect(instance[:col1]).to eq 'type_a'
+      expect(instance.symbolize_keys).to eq(col1: 'type_a')
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults db_configs to a blank DbConfigs instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No db configs
+      YAML
+      expect(eo.db_configs).to be_blank
+    end
+
+    it 'symbolizes db_configs keys' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column: some_value
+      YAML
+      expect(eo.db_configs.keys).to all(be_a Symbol)
+    end
+
+    it 'sets config_obj.db_columns from db_configs after DbConfigs runs' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column: some_value
+      YAML
+
+      expect(@dm.db_columns).to eq(some_column: 'some_value')
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/dialog_before_spec.rb b/spec/models/option_configs/extra_option_configs/dialog_before_spec.rb
new file mode 100644
index 0000000000..bc6504ff3d
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/dialog_before_spec.rb
@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for DialogBefore configuration class.
+# Verifies NamedConfiguration pattern, template validation, and integration through
+# ExtraOptions initialization (clean_dialog_before_def behavior).
+RSpec.describe 'ExtraOptionConfigs::DialogBefore', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::DialogBefore }
+
+  describe 'initialization' do
+    before do
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+    end
+
+    it 'converts string to NamedConfiguration with name attribute' do
+      instance = klass.new(field1: 'test_dialog')
+      nc = instance[:field1]
+      expect(nc).to be_a OptionConfigs::BaseNamedConfiguration
+      expect(nc[:name]).to eq 'test_dialog'
+    end
+
+    it 'reports warning for missing template' do
+      instance = klass.new(field1: 'nonexistent')
+      expect(instance.config_warnings).not_to be_empty
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'produces ActiveModel errors when value is an invalid type' do
+      instance = klass.new(test_field: 12_345)
+      expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
+                                                                            'Expected ActiveModel error on :dialog_before for invalid type, but none found'
+    end
+
+    it 'produces ActiveModel errors (warning level) when template does not exist' do
+      instance = klass.new(test_field: { name: 'nonexistent_template_xyz_999' })
+      expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
+                                                                            'Expected ActiveModel error on :dialog_before for missing template, but none found'
+    end
+
+    it 'has no ActiveModel errors when given valid configuration' do
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog_template_986',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>Test</p>',
+        current_admin: @admin
+      )
+      instance = klass.new(test_field: { name: 'test_dialog_template_986' })
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid dialog_before, got: #{instance.errors.full_messages}"
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults dialog_before to a blank DialogBefore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No dialogs
+      YAML
+      expect(eo.dialog_before).to be_blank
+    end
+
+    it 'converts a string value to a hash with name key' do
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog_template',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1: test_dialog_template
+      YAML
+
+      db = eo.dialog_before[:test1]
+      expect(db).to respond_to(:[])
+      expect(db[:name]).to eq 'test_dialog_template'
+    end
+
+    it 'preserves a hash value with name key' do
+      Admin::MessageTemplate.create!(
+        name: 'test_dialog_hash',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1:
+              name: test_dialog_hash
+      YAML
+
+      db = eo.dialog_before[:test1]
+      expect(db[:name]).to eq 'test_dialog_hash'
+    end
+
+    it 'reports a warning when the named message template does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1: nonexistent_template
+      YAML
+
+      expect(eo.config_warnings).not_to be_empty
+      warn_msg = eo.config_warnings.find { |w| w[:type] == :dialog_before }
+      expect(warn_msg).to be_present
+    end
+
+    it 'reports an error when the value is not a String or Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          dialog_before:
+            test1:
+              - invalid_array_item
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :dialog_before }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes dialog_before keys' do
+      Admin::MessageTemplate.create!(
+        name: 'dialog_sym_test',
+        message_type: :dialog,
+        template_type: :content,
+        template: '<p>test</p>',
+        current_admin: @admin
+      )
+
+      eo = config_for(<<~YAML)
+        default:
+          dialog_before:
+            test1: dialog_sym_test
+      YAML
+
+      expect(eo.dialog_before.keys.first).to be_a Symbol
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb b/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
new file mode 100644
index 0000000000..1b0300c629
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ESignConfig configuration class.
+# Verifies document_reference wrapping, key singularization,
+# model reference resolution, and integration with ActivityLogOptions registry.
+RSpec.describe 'ExtraOptionConfigs::ESignConfig', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::ESignConfig }
+
+  describe 'class structure' do
+    it 'exists and inherits from BaseConfiguration' do
+      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'stores processed value' do
+      expect(klass.store_processed_value?).to be true
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:e_sign)
+    end
+  end
+
+  describe 'prepare_config' do
+    it 'wraps document_reference in {item: ...} if not already wrapped' do
+      raw = { document_reference: { player_contacts: { label: 'Contact' } } }
+      result = klass.prepare_config(raw, nil)
+      expect(result[:document_reference]).to have_key(:item),
+                                             'Expected document_reference to be wrapped in {item: ...}'
+    end
+
+    it 'does not double-wrap document_reference that already has :item key' do
+      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
+      result = klass.prepare_config(raw, nil)
+      expect(result[:document_reference][:item]).not_to have_key(:item),
+                                                        'Expected document_reference not to be double-wrapped'
+    end
+
+    it 'singularizes keys within each reference item' do
+      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
+      result = klass.prepare_config(raw, nil)
+      item = result[:document_reference][:item]
+      expect(item).to have_key(:player_contact),
+                      'Expected pluralized key :player_contacts to be singularized to :player_contact'
+      expect(item).not_to have_key(:player_contacts),
+                          'Expected original pluralized key :player_contacts to be removed after singularization'
+    end
+
+    it 'resolves model references with to_record_label, no_master_association, to_model_name_us' do
+      raw = { document_reference: { item: { player_contacts: { label: 'My Label' } } } }
+      result = klass.prepare_config(raw, nil)
+      ref = result[:document_reference][:item][:player_contact]
+      expect(ref).to have_key(:to_record_label),
+                     'Expected :to_record_label to be set on resolved reference'
+      expect(ref).to have_key(:to_model_name_us),
+                     'Expected :to_model_name_us to be set on resolved reference'
+    end
+
+    it 'returns nil from prepare_config when raw is nil' do
+      result = klass.prepare_config(nil, nil)
+      expect(result).to be_nil
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/embed_spec.rb b/spec/models/option_configs/extra_option_configs/embed_spec.rb
new file mode 100644
index 0000000000..8e8a1efb1c
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/embed_spec.rb
@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Embed configuration class.
+# Verifies resource_name handling, validate callbacks, and integration through
+# ExtraOptions initialization (clean_embed_def behavior).
+RSpec.describe 'ExtraOptionConfigs::Embed', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Embed }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:embed)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores resource_name from string input' do
+      instance = klass.new('some_resource')
+      expect(instance.embed[:resource_name]).to eq 'some_resource'
+    end
+
+    it 'stores resource_name from hash input' do
+      instance = klass.new(resource_name: 'some_resource')
+      expect(instance.embed[:resource_name]).to eq 'some_resource'
+    end
+
+    it 'returns blank when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'produces ActiveModel errors on the instance when resource does not exist' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          embed: nonexistent_resource_xyz_999
+      YAML
+      eo = config_for(yaml)
+
+      processed = klass.prepare_config('nonexistent_resource_xyz_999', eo)
+      instance = klass.new(processed)
+      expect(instance.errors.any? { |e| e.attribute == :embed }).to be(true),
+                                                                    'Expected ActiveModel error on :embed for non-existent resource, but none found on instance'
+    end
+
+    it 'has no ActiveModel errors on the instance when embed is valid' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          embed: player_contacts
+      YAML
+      eo = config_for(yaml)
+
+      processed = klass.prepare_config('player_contacts', eo)
+      instance = klass.new(processed)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid embed, got: #{instance.errors.full_messages}"
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'leaves embed as nil when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No embed
+      YAML
+      expect(eo.embed).to be_nil
+    end
+
+    it 'converts a string resource_name into a hash with resource_name key' do
+      eo = config_for(<<~YAML)
+        default:
+          embed: dynamic_model__some_resource
+      YAML
+
+      expect(eo.embed).to be_a Hash
+      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
+    end
+
+    it 'preserves a hash-style embed with resource_name' do
+      eo = config_for(<<~YAML)
+        default:
+          embed:
+            resource_name: dynamic_model__some_resource
+      YAML
+
+      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
+    end
+
+    it 'warns when the embedded resource does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          embed:
+            resource_name: dynamic_model__nonexistent_model
+      YAML
+
+      expect(eo.config_warnings).not_to be_empty
+      warn = eo.config_warnings.find { |w| w[:type] == :embed }
+      expect(warn).to be_present
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/field_configs_spec.rb b/spec/models/option_configs/extra_option_configs/field_configs_spec.rb
new file mode 100644
index 0000000000..81b15d8ff6
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/field_configs_spec.rb
@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for FieldConfigs configuration class.
+# Verifies field config merging, validation, standalone def integration,
+# and validate callbacks through ExtraOptions initialization (clean_field_configs behavior).
+RSpec.describe 'ExtraOptionConfigs::FieldConfigs', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldConfigs }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:field_configs)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores the hash as field_configs attribute' do
+      instance = klass.new(test1: { caption_before: 'Test' })
+      expect(instance.field_configs).to eq(test1: { caption_before: 'Test' })
+    end
+
+    it 'defaults to empty hash when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.field_configs).to eq({})
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'produces ActiveModel errors when a field value is not a Hash' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          field_configs:
+            test_field: not_a_hash
+      YAML
+      eo = config_for(yaml)
+
+      raw = { test_field: 'not_a_hash' }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                            'Expected ActiveModel error on :field_configs for non-Hash field value, but none found on instance'
+    end
+
+    it 'produces ActiveModel errors when fields are not in the field list' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          field_configs:
+            unknown_field:
+              caption_before: Test Caption
+      YAML
+      eo = config_for(yaml)
+
+      raw = { unknown_field: { caption_before: 'Test Caption' } }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                            'Expected ActiveModel error on :field_configs for field not in field list, but none found on instance'
+    end
+
+    it 'produces ActiveModel errors when field_configs contain invalid keys' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          field_configs:
+            test_field:
+              totally_invalid_key: some_value
+      YAML
+      eo = config_for(yaml)
+
+      raw = { test_field: { totally_invalid_key: 'some_value' } }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
+                                                                            'Expected ActiveModel error on :field_configs for invalid keys, but none found on instance'
+    end
+
+    it 'has no ActiveModel errors when field_configs are valid' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          field_configs:
+            test_field:
+              caption_before: A Caption
+      YAML
+      eo = config_for(yaml)
+
+      raw = { test_field: { caption_before: 'A Caption' } }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid field_configs, got: #{instance.errors.full_messages}"
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults field_configs to an empty hash when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No field configs
+      YAML
+      expect(eo.field_configs).to eq({})
+    end
+
+    it 'merges field_configs into the standalone configs (caption_before, labels, etc.)' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          field_configs:
+            test1:
+              caption_before: Caption for test1
+              labels: Label for test1
+            test2:
+              show_if:
+                test1: some_value
+      YAML
+
+      expect(eo.caption_before[:test1]).to be_present
+      expect(eo.labels[:test1]).to eq 'Label for test1'
+      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
+    end
+
+    it 'reports an error when field_configs references fields not in the field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            nonexistent_field:
+              labels: Some label
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'reports an error when field_configs contains invalid config keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1:
+              invalid_key: some value
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'reports an error when a field config value is not a Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1: not_a_hash
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :field_configs }
+      expect(err).to be_present
+    end
+
+    it 'stores raw_field_configs as a deep clone before standalone defs are merged' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_configs:
+            test1:
+              labels: Raw label
+          labels:
+            test1: Standalone label
+      YAML
+
+      expect(eo.raw_field_configs).to be_a Hash
+      expect(eo.raw_field_configs[:test1]).to be_a Hash
+      original_fc = eo.field_configs[:test1].dup
+      eo.raw_field_configs[:test1][:labels] = 'Modified'
+      expect(eo.field_configs[:test1]).to eq original_fc
+    end
+
+    it 'merges standalone configs back into field_configs for valid fields' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          labels:
+            test1: Standalone Label 1
+          caption_before:
+            test2: Standalone caption
+      YAML
+
+      expect(eo.field_configs[:test1]).to include(labels: 'Standalone Label 1')
+      expect(eo.field_configs[:test2]).to be_a Hash
+      expect(eo.field_configs[:test2]).to have_key(:caption_before)
+    end
+
+    it 'does not include standalone configs for fields not in the field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          labels:
+            test1: Included
+            not_a_field: Excluded
+      YAML
+
+      expect(eo.field_configs).not_to have_key(:not_a_field)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/field_options_spec.rb b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
new file mode 100644
index 0000000000..1a814eb3a1
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for FieldOptions configuration class.
+# Verifies alt_options preprocessing and integration through
+# ExtraOptions initialization (clean_field_options_def behavior).
+RSpec.describe 'ExtraOptionConfigs::FieldOptions', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldOptions }
+
+  describe 'initialization' do
+    it 'converts alt_options Array to Hash' do
+      instance = klass.new(
+        field1: { edit_as: { alt_options: %w[ChoiceA ChoiceB] } }
+      )
+      ao = instance[:field1][:edit_as][:alt_options]
+      expect(ao).to be_a Hash
+      expect(ao[:ChoiceA]).to eq 'choicea'
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults field_options to a blank FieldOptions instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No field options
+      YAML
+      expect(eo.field_options).to be_blank
+    end
+
+    it 'preserves field_options and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              no_downcase: true
+      YAML
+      expect(eo.field_options[:test1]).to eq(no_downcase: true)
+    end
+
+    it 'converts edit_as.alt_options from Array to Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              edit_as:
+                field_type: select
+                alt_options:
+                  - Choice A
+                  - Choice B
+      YAML
+
+      ao = eo.field_options[:test1][:edit_as][:alt_options]
+      expect(ao).to be_a Hash
+      expect(ao[:'Choice A']).to eq 'choice a'
+      expect(ao[:'Choice B']).to eq 'choice b'
+    end
+
+    it 'preserves edit_as.alt_options when already a Hash' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          field_options:
+            test1:
+              edit_as:
+                field_type: select
+                alt_options:
+                  'Option 1': opt1
+                  'Option 2': opt2
+      YAML
+
+      ao = eo.field_options[:test1][:edit_as][:alt_options]
+      expect(ao).to be_a Hash
+      expect(ao[:'Option 1']).to eq 'opt1'
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/fields_spec.rb b/spec/models/option_configs/extra_option_configs/fields_spec.rb
new file mode 100644
index 0000000000..8bcc52b085
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/fields_spec.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Fields configuration class.
+# Verifies configure_direct with type :array and integration through
+# ExtraOptions initialization (clean_fields_def behavior).
+RSpec.describe 'ExtraOptionConfigs::Fields', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Fields }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :array' do
+      expect(klass.option_types[:direct]).to include(:fields)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores the array as fields attribute' do
+      instance = klass.new(%w[field1 field2])
+      expect(instance.fields).to eq %w[field1 field2]
+    end
+
+    it 'defaults to empty array when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.fields).to eq []
+    end
+
+    it 'returns blank when initialized with empty array' do
+      instance = klass.new([])
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults fields to an empty array when not specified in options' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No fields
+      YAML
+      expect(eo.fields).to be_an Array
+    end
+
+    it 'preserves a provided field list' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+      YAML
+      expect(eo.fields).to eq %w[test1 test2]
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/filestore_spec.rb b/spec/models/option_configs/extra_option_configs/filestore_spec.rb
new file mode 100644
index 0000000000..3d9f55ee4b
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/filestore_spec.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Filestore configuration class.
+# Verifies configure_direct with type :hash and integration through
+# ExtraOptions initialization (clean_filestore_def behavior).
+RSpec.describe 'ExtraOptionConfigs::Filestore', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Filestore }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:filestore)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores entire hash as single attribute' do
+      instance = klass.new(container: { path: '/test' })
+      expect(instance.filestore).to eq(container: { path: '/test' })
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(container: {})
+      expect(instance.symbolize_keys).to eq(container: {})
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults filestore to a blank Filestore when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No filestore
+      YAML
+      expect(eo.filestore).to be_a OptionConfigs::ExtraOptionConfigs::Filestore
+      expect(eo.filestore).to be_blank
+    end
+
+    it 'preserves and symbolizes filestore keys' do
+      eo = config_for(<<~YAML)
+        default:
+          filestore:
+            always_use_this_for_access_control: true
+      YAML
+      expect(eo.filestore.symbolize_keys).to eq(always_use_this_for_access_control: true)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/if_condition_spec.rb b/spec/models/option_configs/extra_option_configs/if_condition_spec.rb
new file mode 100644
index 0000000000..5af7aaf3d7
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/if_condition_spec.rb
@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for IfCondition configuration class and the three split classes
+# (CreatableIf, EditableIf, ShowableIf) that replaced AccessIf.
+# Verifies configure_direct with type :hash, store_processed_value?,
+# and integration through ExtraOptions initialization (clean_access_if_def behavior).
+RSpec.describe 'ExtraOptionConfigs::IfCondition and access_if classes', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  describe 'IfCondition' do
+    let(:klass) { OptionConfigs::ExtraOptionConfigs::IfCondition }
+
+    it 'exists under ExtraOptionConfigs namespace' do
+      expect(klass).to be_a Class
+    end
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:conditions)
+      expect(klass.direct_types[:conditions]).to eq(:hash)
+    end
+
+    it 'stores entire hash as single conditions attribute' do
+      instance = klass.new(always: true, user_is_creator: true)
+      expect(instance.conditions).to eq(always: true, user_is_creator: true)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'returns not blank when initialized with data' do
+      instance = klass.new(always: true)
+      expect(instance).not_to be_blank
+    end
+
+    it 'symbolizes keys on initialization' do
+      instance = klass.new('always' => true)
+      expect(instance.conditions).to have_key(:always)
+    end
+
+    it 'handles nil initialization' do
+      instance = klass.new(nil)
+      expect(instance.conditions).to eq({})
+      expect(instance).to be_blank
+    end
+
+    it 'supports symbolize_keys for backward compatibility' do
+      instance = klass.new(always: true, never: false)
+      expect(instance.symbolize_keys).to eq(always: true, never: false)
+    end
+  end
+
+  describe 'if_condition classes (split from AccessIf)' do
+    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+
+        it 'exists under ExtraOptionConfigs namespace' do
+          expect(klass).to be_a Class
+        end
+
+        it 'uses configure_direct with type :hash' do
+          expect(klass.option_types[:direct]).to be_present
+        end
+      end
+    end
+  end
+
+  describe 'if_condition classes (converted to BaseConfiguration)' do
+    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+        let(:attr_name) { class_name.to_s.underscore.to_sym }
+
+        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+        end
+
+        it 'does not inherit from ConfigBase' do
+          expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+        end
+
+        it 'declares configure_direct with type :hash' do
+          expect(klass.option_types[:direct]).to include(attr_name)
+        end
+
+        it 'stores the hash as the attribute' do
+          instance = klass.new(always: true)
+          expect(instance.send(attr_name)).to eq(always: true)
+        end
+
+        it 'supports hash-like bracket access' do
+          instance = klass.new(always: true)
+          expect(instance[:always]).to eq true
+        end
+
+        it 'defaults to empty hash when initialized with nil' do
+          instance = klass.new(nil)
+          expect(instance.send(attr_name)).to eq({})
+          expect(instance).to be_blank
+        end
+      end
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults all access_if attributes to empty hashes' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No access
+      YAML
+
+      expect(eo.creatable_if).to eq({})
+      expect(eo.editable_if).to eq({})
+      expect(eo.showable_if).to eq({})
+    end
+
+    it 'preserves and symbolizes creatable_if, editable_if, showable_if' do
+      eo = config_for(<<~YAML)
+        default:
+          creatable_if:
+            always: true
+          editable_if:
+            never: true
+          showable_if:
+            user_is_creator: true
+      YAML
+
+      expect(eo.creatable_if).to eq(always: true)
+      expect(eo.editable_if).to eq(never: true)
+      expect(eo.showable_if).to eq(user_is_creator: true)
+    end
+
+    it 'access_if classes store processed hash values (via store_processed_value?)' do
+      eo = config_for(<<~YAML)
+        default:
+          creatable_if:
+            always: true
+          editable_if:
+            never: true
+          showable_if:
+            user_is_creator: true
+      YAML
+
+      expect(eo.creatable_if).to be_a Hash
+      expect(eo.creatable_if[:always]).to eq true
+      expect(eo.editable_if).to be_a Hash
+      expect(eo.editable_if[:never]).to eq true
+      expect(eo.showable_if).to be_a Hash
+      expect(eo.showable_if[:user_is_creator]).to eq true
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/integration_spec.rb b/spec/models/option_configs/extra_option_configs/integration_spec.rb
new file mode 100644
index 0000000000..b81c45ca79
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/integration_spec.rb
@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Integration tests for ExtraOptions initialization sequence.
+# Verifies config_instances, attribute storage, old clean_ method removal,
+# resource_name initialization, config_obj mutation, and full end-to-end
+# initialization with multiple config areas.
+RSpec.describe 'ExtraOptions integration', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # config_instances
+  # ──────────────────────────────────────────────────────────────
+  describe 'config_instances' do
+    it 'stores config_instances after initialization (empty since all converted to BaseConfiguration)' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Integration Test
+          fields:
+            - test1
+      YAML
+
+      expect(eo).to respond_to(:config_instances)
+      expect(eo.config_instances).to be_a Hash
+      expect(eo.config_instances).to be_empty
+    end
+
+    it 'no ConfigBase classes remain — config_instances is empty' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Full Config
+          fields:
+            - test1
+      YAML
+
+      expect(eo.config_instances).to be_empty
+
+      ExtraOptionConfigsSupport::FIELD_KEYED_CLASSES.each do |class_name|
+        key = class_name.to_s.underscore.to_sym
+        expect(eo.config_instances).not_to have_key(key),
+                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
+      end
+
+      ExtraOptionConfigsSupport::TYPED_CONFIG_CLASSES.each do |class_name|
+        key = ExtraOptionConfigsSupport::EXPECTED_CONFIG_CLASSES.key(class_name)
+        expect(eo.config_instances).not_to have_key(key),
+                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Attribute storage patterns
+  # ──────────────────────────────────────────────────────────────
+  describe 'attribute storage patterns' do
+    it 'caption_before is stored directly as a CaptionBefore instance on ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Direct storage test
+      YAML
+
+      expect(eo.caption_before).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
+      expect(eo.caption_before[:test1]).to be_present
+    end
+
+    it 'field-keyed classes are stored directly as BaseConfiguration instances' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          labels:
+            test1: Test Label
+          show_if:
+            test1:
+              other_field: val
+          field_options:
+            test1:
+              no_downcase: true
+          db_configs:
+            test1: some_value
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      expect(eo.labels).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.show_if).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.field_options).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.db_configs).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+      expect(eo.preset_fields).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'BaseConfiguration attribute values are accessible on ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Matching Test
+          fields:
+            - test1
+            - test2
+          labels:
+            test1: Test One
+          view_options:
+            data_attribute: test1
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      expect(eo.label).to eq 'Matching Test'
+      expect(eo.fields).to eq %w[test1 test2]
+      expect(eo.labels[:test1]).to eq 'Test One'
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options[:data_attribute]).to eq 'test1'
+      expect(eo.preset_fields[:test1]).to eq 'preset_val'
+    end
+
+    it 'caption_before values match between CaptionBefore instance and ExtraOptions' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1: Simple caption text
+      YAML
+
+      cb = eo.caption_before
+      expect(cb).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
+      expect(cb[:test1][:caption]).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # config_obj mutation
+  # ──────────────────────────────────────────────────────────────
+  describe 'config_obj mutation handling' do
+    it 'sets config_obj.db_columns from db_configs after DbConfigs runs' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column: some_value
+      YAML
+
+      expect(@dm.db_columns).to eq(some_column: 'some_value')
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Old clean_ methods removed
+  # ──────────────────────────────────────────────────────────────
+  describe 'old clean_ methods removed' do
+    let(:removed_clean_methods) do
+      %i[
+        clean_label_def
+        clean_caption_before_def
+        clean_dialog_before_def
+        clean_labels_def
+        clean_show_if_def
+        clean_save_action_def
+        clean_view_options_def
+        clean_db_configs_def
+        clean_fields_def
+        clean_field_options_def
+        clean_filestore_def
+        clean_access_if_def
+        clean_valid_if_def
+        clean_embed_def
+        clean_references_def
+        clean_save_triggers
+        clean_batch_triggers
+        clean_config_triggers
+        clean_preset_fields
+        clean_set_variables_def
+        clean_field_configs
+      ]
+    end
+
+    it 'no longer defines any clean_ instance methods' do
+      removed_clean_methods.each do |method_name|
+        expect(OptionConfigs::ExtraOptions.method_defined?(method_name, false))
+          .to be(false), "Expected #{method_name} to be removed from ExtraOptions"
+      end
+    end
+
+    it 'still initializes correctly without clean_ methods' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          fields:
+            - test_field
+          caption_before:
+            test_field: A Caption
+          show_if:
+            test_field:
+              test_field2: value
+          view_options:
+            show_result_options: true
+      YAML
+      eo = config_for(yaml)
+      expect(eo.label).to eq('Test')
+      expect(eo.caption_before).to be_present
+      expect(eo.show_if).to be_present
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # resource_name initialization
+  # ──────────────────────────────────────────────────────────────
+  describe 'resource_name initialization' do
+    it 'sets resource_name from config_obj and option name' do
+      eo = config_for(<<~YAML)
+        my_option:
+          label: Test
+      YAML
+
+      expect(eo.resource_name).to include('my_option')
+      expect(eo.resource_item_name).to eq eo.resource_name
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Full initialization sequence
+  # ──────────────────────────────────────────────────────────────
+  describe 'full initialization with multiple configs' do
+    it 'initializes all clean_ methods in sequence without errors for valid config' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          label: Full Test
+          labels:
+            test1: Test One
+            test2: Test Two
+          caption_before:
+            test1: Caption One
+          view_options:
+            data_attribute: test1
+          save_action:
+            on_save:
+              label: Saved
+          field_options:
+            test1:
+              no_downcase: true
+          preset_fields:
+            test1: preset_val
+      YAML
+
+      expect(eo.config_errors).to be_empty
+      expect(eo.label).to eq 'Full Test'
+      expect(eo.fields).to eq %w[test1 test2]
+      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
+      expect(eo.caption_before[:test1]).to respond_to(:[])
+      expect(eo.caption_before[:test1][:caption]).to be_present
+      expect(eo.view_options[:data_attribute]).to eq 'test1'
+      expect(eo.save_action[:on_create][:label]).to eq 'Saved'
+      expect(eo.field_options[:test1][:no_downcase]).to eq true
+      expect(eo.preset_fields[:test1]).to eq 'preset_val'
+    end
+
+    it 'handles multiple named option configs from a single definition' do
+      configs = all_configs_for(<<~YAML)
+        option_a:
+          label: Option A
+          fields:
+            - test1
+        option_b:
+          label: Option B
+          fields:
+            - test2
+      YAML
+
+      names = configs.map(&:name)
+      expect(names).to include(:option_a)
+      expect(names).to include(:option_b)
+      expect(configs.length).to be >= 2
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/label_spec.rb b/spec/models/option_configs/extra_option_configs/label_spec.rb
new file mode 100644
index 0000000000..663fae36de
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/label_spec.rb
@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Label configuration class.
+# Verifies configure_direct with type :string, store_processed_value?,
+# and prepare_config defaulting to humanized name from parent.
+RSpec.describe 'ExtraOptionConfigs::Label', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Label }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :string' do
+      expect(klass.option_types[:direct]).to include(:label)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores the string as label attribute' do
+      instance = klass.new('My Label')
+      expect(instance.label).to eq 'My Label'
+    end
+
+    it 'defaults to empty string when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.label).to eq ''
+    end
+
+    it 'uses prepare_config to default to humanized name from parent' do
+      expect(klass).to respond_to(:prepare_config)
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults label to a humanized version of the config name' do
+      eo = config_for(<<~YAML)
+        my_custom_name:
+          fields:
+            - test1
+      YAML
+      expect(eo.label).to eq 'My custom name'
+    end
+
+    it 'preserves an explicitly set label' do
+      eo = config_for(<<~YAML)
+        default:
+          label: Custom Label
+      YAML
+      expect(eo.label).to eq 'Custom Label'
+    end
+
+    it 'defaults label to humanized name when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+      YAML
+      expect(eo.label).to eq 'Default'
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/labels_spec.rb b/spec/models/option_configs/extra_option_configs/labels_spec.rb
new file mode 100644
index 0000000000..f6584813c4
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/labels_spec.rb
@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Labels configuration class (field-keyed BaseConfiguration).
+# Verifies hash-like interface and integration through
+# ExtraOptions initialization (clean_labels_def behavior).
+RSpec.describe 'ExtraOptionConfigs::Labels', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Labels }
+
+  describe 'initialization' do
+    it 'stores plain string values' do
+      instance = klass.new(field1: 'Label One', field2: 'Label Two')
+      expect(instance[:field1]).to eq 'Label One'
+      expect(instance[:field2]).to eq 'Label Two'
+    end
+
+    it 'symbolize_keys returns a plain Hash' do
+      instance = klass.new(field1: 'Label One', field2: 'Label Two')
+      expect(instance.symbolize_keys).to eq(field1: 'Label One', field2: 'Label Two')
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults labels to a blank Labels instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No labels
+      YAML
+      expect(eo.labels).to be_blank
+    end
+
+    it 'preserves explicitly set labels and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          labels:
+            test1: Test One
+            test2: Test Two
+      YAML
+
+      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/nfs_store_config_spec.rb b/spec/models/option_configs/extra_option_configs/nfs_store_config_spec.rb
new file mode 100644
index 0000000000..79ce3206d2
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/nfs_store_config_spec.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for NfsStoreConfig configuration class.
+# Verifies key validation for nfs_store top-level and can sub-keys,
+# pipeline delegation, and integration with ActivityLogOptions registry.
+RSpec.describe 'ExtraOptionConfigs::NfsStoreConfig', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::NfsStoreConfig }
+
+  describe 'class structure' do
+    it 'exists and inherits from BaseConfiguration' do
+      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
+    end
+
+    it 'stores processed value' do
+      expect(klass.store_processed_value?).to be true
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:nfs_store)
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'produces ActiveModel errors for invalid top-level nfs_store keys' do
+      raw = { always_use_this_for_access_control: true, invalid_key_xyz: 'bad' }
+      instance = klass.new(raw)
+      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
+                                                                        'Expected ActiveModel error on :nfs_store for invalid top-level keys'
+    end
+
+    it 'produces ActiveModel errors for invalid can sub-keys' do
+      raw = { can: { download_if: true, bogus_permission: 'bad' } }
+      instance = klass.new(raw)
+      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
+                                                                        'Expected ActiveModel error on :nfs_store for invalid can sub-keys'
+    end
+
+    it 'has no ActiveModel errors when all keys are valid' do
+      raw = { always_use_this_for_access_control: true, can: { download_if: true } }
+      instance = klass.new(raw)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid nfs_store keys, got: #{instance.errors.full_messages}"
+    end
+
+    it 'has no ActiveModel errors when nfs_store is nil' do
+      instance = klass.new(nil)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for nil nfs_store, got: #{instance.errors.full_messages}"
+    end
+  end
+
+  describe 'prepare_config' do
+    it 'delegates pipeline cleaning via prepare_config' do
+      raw = { pipeline: [], user_file_actions: [] }
+      expect(NfsStore::Config::ExtraOptions).to receive(:clean_def).with(raw)
+      klass.prepare_config(raw, nil)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/preset_fields_spec.rb b/spec/models/option_configs/extra_option_configs/preset_fields_spec.rb
new file mode 100644
index 0000000000..e23adbbb53
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/preset_fields_spec.rb
@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for PresetFields configuration class (field-keyed BaseConfiguration).
+# Verifies hash-like interface and integration through
+# ExtraOptions initialization (clean_preset_fields behavior).
+RSpec.describe 'ExtraOptionConfigs::PresetFields', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::PresetFields }
+
+  describe 'initialization' do
+    it 'stores preset values directly' do
+      instance = klass.new(field1: 'default_val')
+      expect(instance[:field1]).to eq 'default_val'
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults preset_fields to a blank PresetFields instance' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No presets
+      YAML
+      expect(eo.preset_fields).to be_blank
+    end
+
+    it 'preserves and symbolizes preset_fields' do
+      eo = config_for(<<~YAML)
+        default:
+          preset_fields:
+            test1: default_value
+            test2: another_value
+      YAML
+      expect(eo.preset_fields.symbolize_keys).to eq(test1: 'default_value', test2: 'another_value')
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/references_spec.rb b/spec/models/option_configs/extra_option_configs/references_spec.rb
new file mode 100644
index 0000000000..0d50eb9e64
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/references_spec.rb
@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for References configuration class and the source_attribute pattern.
+# Verifies:
+# - source_attribute reads raw input from :references (a base_key_attribute)
+# - references_config stores the References instance with ReferenceEntry named configurations
+# - references stores the enriched hash with computed metadata (views consume this)
+# - ReferenceEntry holds only admin-configured input keys (round-trip serializable)
+# - prepare_config normalization (singularize, composite keys, class resolution)
+# - reprocess, validate callbacks, and integration through ExtraOptions initialization
+RSpec.describe 'ExtraOptionConfigs::References', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::References }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:references)
+    end
+
+    it 'defaults to nil when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance.references).to be_nil
+    end
+
+    it 'declares source_attribute as :references' do
+      expect(klass.source_attribute).to eq(:references)
+    end
+
+    it 'has store_processed_value? returning true' do
+      expect(klass.store_processed_value?).to be(true)
+    end
+
+    it 'defines NamedConfiguration with admin input attributes' do
+      expect(klass.const_defined?(:NamedConfiguration)).to be(true)
+      nc = klass::NamedConfiguration
+      expected_attrs = %i[
+        label result_label from without_reference add add_with
+        filter_by order_by limit type_config
+        view_as view_options showable_if creatable_if
+        prevent_disable also_disable_record allow_disable_if_not_editable
+        prevent_reload_on_save action_position
+      ]
+      expected_attrs.each do |attr|
+        expect(nc.option_types[:simple]).to include(attr),
+                                            "Expected NamedConfiguration to have attribute :#{attr}"
+      end
+    end
+
+    it 'aliases NamedConfiguration as ReferenceEntry' do
+      expect(klass::ReferenceEntry).to eq(klass::NamedConfiguration)
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'produces ActiveModel errors on the instance when reference class does not exist' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          references:
+            nonexistent_model_xyz_999:
+              from: this
+              add: many
+      YAML
+      eo = config_for(yaml)
+
+      raw = { nonexistent_model_xyz_999: { from: 'this', add: 'many' } }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors.any? { |e| e.attribute == :references }).to be(true),
+                                                                         'Expected ActiveModel error on :references for non-existent class, but none found on instance'
+    end
+
+    it 'has no ActiveModel errors on the instance when references are valid' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          references:
+            player_contact:
+              from: this
+              add: many
+      YAML
+      eo = config_for(yaml)
+
+      raw = { player_contact: { from: 'this', add: 'many' } }
+      processed = klass.prepare_config(raw, eo)
+      instance = klass.new(processed)
+      expect(instance.errors).to be_empty,
+                                 "Expected no ActiveModel errors for valid references, got: #{instance.errors.full_messages}"
+    end
+  end
+
+  describe 'References.reprocess' do
+    it 'exists as a class method on References' do
+      expect(klass).to respond_to(:reprocess)
+    end
+
+    it 're-processes references after post-initialization mutation' do
+      yaml = <<~YAML
+        default:
+          label: Test
+          references:
+            player_contact:
+              from: this
+              add: many
+      YAML
+      eo = config_for(yaml)
+
+      # Initial references should have been processed
+      expect(eo.references).to be_a(Hash)
+      initial_ref = eo.references[:player_contact]
+      expect(initial_ref).to be_present
+      expect(initial_ref[:player_contact][:to_record_label]).to be_present
+
+      # Mutate references with a raw hash using plural keys
+      eo.references = { player_contacts: { from: 'this', add: 'many' } }
+
+      # Call reprocess to re-run prepare_config on the mutated value
+      klass.reprocess(eo)
+
+      # After reprocessing, plural keys should be singularized
+      expect(eo.references).to be_a(Hash)
+      reprocessed_ref = eo.references[:player_contact]
+      expect(reprocessed_ref).to be_present, 'Expected plural key :player_contacts to be singularized to :player_contact'
+      expect(reprocessed_ref[:player_contact][:to_record_label]).to be_present
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'leaves references as nil when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No references
+      YAML
+      expect(eo.references).to be_nil
+    end
+
+    it 'converts a hash-style references, singularizing keys' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            player_infos:
+              label: Player Info Ref
+      YAML
+
+      expect(eo.references).to be_a Hash
+      ref_keys = eo.references.keys
+      ref_keys.each do |k|
+        inner = eo.references[k]
+        expect(inner).to be_a Hash
+      end
+    end
+
+    it 'converts an array-style references to a hash' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            - player_infos:
+                label: Player Info Ref
+      YAML
+
+      expect(eo.references).to be_a Hash
+    end
+
+    it 'warns when a referenced model does not exist' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            nonexistent_model_xyz:
+              label: Bad Reference
+      YAML
+
+      has_warning = eo.config_warnings.any? { |w| w[:type] == :references }
+      expect(eo.references).to be_a Hash
+    end
+  end
+
+  describe 'source_attribute integration' do
+    it 'stores the References instance at references_config' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            player_contact:
+              label: Contact
+              from: this
+              add: many
+      YAML
+
+      expect(eo.references_config).to be_a(klass)
+    end
+
+    it 'stores the enriched hash at references' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            player_contact:
+              label: Contact
+              from: this
+              add: many
+      YAML
+
+      expect(eo.references).to be_a(Hash)
+      inner = eo.references[:player_contact]
+      expect(inner).to be_a(Hash)
+      expect(inner[:player_contact][:to_record_label]).to be_present
+      expect(inner[:player_contact][:to_model_name_us]).to be_present
+    end
+
+    it 'references_config.configurations holds ReferenceEntry objects with input-only keys' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            player_contact:
+              label: Contact
+              from: this
+              add: many
+              filter_by:
+                rec_type: test
+      YAML
+
+      rc = eo.references_config
+      expect(rc.configurations).to be_a(Hash)
+
+      entry = rc.configurations[:player_contact]
+      expect(entry).to be_a(klass::ReferenceEntry)
+      expect(entry[:label]).to eq('Contact')
+      expect(entry[:from]).to eq('this')
+      expect(entry[:add]).to eq('many')
+      expect(entry[:filter_by]).to eq({ rec_type: 'test' })
+
+      # Computed keys should NOT be in the ReferenceEntry
+      klass::COMPUTED_KEYS.each do |computed_key|
+        expect(entry[computed_key]).to be_nil,
+                                       "Expected ReferenceEntry NOT to contain computed key :#{computed_key}"
+      end
+    end
+
+    it 'references_config is nil when no references are configured' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No references
+      YAML
+
+      expect(eo.references_config).to be_a(klass)
+      expect(eo.references_config.configurations).to be_empty
+    end
+
+    it 'collects errors/warnings via references_config (not lost on source_attribute pattern)' do
+      eo = config_for(<<~YAML)
+        default:
+          references:
+            nonexistent_model_xyz:
+              label: Bad Reference
+      YAML
+
+      has_warning = eo.config_warnings.any? { |w| w[:type] == :references }
+      expect(has_warning).to be(true), 'Expected config_warnings to include a :references warning'
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/registry_spec.rb b/spec/models/option_configs/extra_option_configs/registry_spec.rb
new file mode 100644
index 0000000000..9a283d7811
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/registry_spec.rb
@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ConfigBase, config_class_registry, config_class_attributes,
+# field-keyed and typed class structure, configure_direct, and
+# configure_typed_attribute — the infrastructure that underpins
+# all ExtraOptionConfigs subclasses.
+RSpec.describe 'ExtraOptionConfigs registry and class structure', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ConfigBase
+  # ──────────────────────────────────────────────────────────────
+  describe 'OptionConfigs::ExtraOptionConfigs::ConfigBase' do
+    it 'exists as a class' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to be_a Class
+    end
+
+    it 'includes ActiveModel::Validations' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase.ancestors).to include(ActiveModel::Validations)
+    end
+
+    it 'provides managed_attributes class method' do
+      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to respond_to(:managed_attributes)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Registry key alignment and config_class_attributes
+  # ──────────────────────────────────────────────────────────────
+  describe 'config_class_registry and config_class_attributes' do
+    it 'config_class_registry keys match ExtraOptions attribute names' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      ExtraOptionConfigsSupport::EXPECTED_CONFIG_CLASSES.each_key do |attr_key|
+        expect(registry).to have_key(attr_key),
+                            "Expected config_class_registry to have key :#{attr_key}"
+      end
+    end
+
+    it 'registry class names are singular (no trailing s on Triggers/Variables)' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      expect(registry[:save_trigger].name).to include('SaveTrigger')
+      expect(registry[:save_trigger].name).not_to include('SaveTriggers')
+      expect(registry[:batch_trigger].name).to include('BatchTrigger')
+      expect(registry[:batch_trigger].name).not_to include('BatchTriggers')
+      expect(registry[:config_trigger].name).to include('ConfigTrigger')
+      expect(registry[:config_trigger].name).not_to include('ConfigTriggers')
+      expect(registry[:set_variables].name).to include('SetVariable')
+    end
+
+    it 'AccessIf is split into CreatableIf, EditableIf, ShowableIf' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      expect(registry).not_to have_key(:access_if)
+      expect(registry).to have_key(:creatable_if)
+      expect(registry).to have_key(:editable_if)
+      expect(registry).to have_key(:showable_if)
+    end
+
+    it 'provides config_class_attributes derived from registry keys' do
+      attrs = OptionConfigs::ExtraOptions.config_class_attributes
+      expect(attrs).to be_an Array
+      ExtraOptionConfigsSupport::EXPECTED_CONFIG_CLASSES.each_key do |key|
+        expect(attrs).to include(key),
+                         "Expected config_class_attributes to include :#{key}"
+      end
+    end
+
+    it 'base_key_attributes does not overlap config class attributes (except source_attribute keys)' do
+      base = OptionConfigs::ExtraOptions.base_key_attributes
+      config_attrs = OptionConfigs::ExtraOptions.config_class_attributes
+      # source_attribute classes read from a base_key_attribute, so :references
+      # appears in base_key_attributes but not in config_class_attributes
+      overlap = base & config_attrs
+      expect(overlap).to be_empty,
+                         "base_key_attributes should not overlap config_class_attributes, but found: #{overlap}"
+    end
+
+    it 'base_key_attributes includes source_attribute keys for source_attribute classes' do
+      base = OptionConfigs::ExtraOptions.base_key_attributes
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      registry.each do |_key, config_class|
+        next unless config_class.respond_to?(:source_attribute) && config_class.source_attribute
+
+        expect(base).to include(config_class.source_attribute),
+                         "Expected base_key_attributes to include :#{config_class.source_attribute} " \
+                         "for source_attribute class #{config_class.name}"
+      end
+    end
+
+    it 'key_attributes includes both base and config class attributes' do
+      all = OptionConfigs::ExtraOptions.key_attributes
+      base = OptionConfigs::ExtraOptions.base_key_attributes
+      config = OptionConfigs::ExtraOptions.config_class_attributes
+      expect(all).to include(*base)
+      expect(all).to include(*config)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # configure_typed_attribute in OptionsHandler
+  # ──────────────────────────────────────────────────────────────
+  describe 'configure_typed_attribute' do
+    it 'is available as a class method via OptionsHandler' do
+      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_typed_attribute)
+    end
+
+    it 'registers the attribute in option_types[:typed]' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+      end
+      expect(test_class.option_types[:typed]).to include(:test_conditions)
+    end
+
+    it 'stores the type class reference in typed_attribute_types' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+      end
+      expect(test_class.typed_attribute_types[:test_conditions]).to eq(OptionConfigs::ExtraOptionConfigs::IfCondition)
+    end
+
+    it 'auto-initializes the attribute from hash configuration' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+
+        def config_text=(_value); end
+      end
+      instance = test_class.new(nil, use_hash_config: { test_conditions: { always: true } })
+      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
+      expect(instance.test_conditions.conditions).to eq(always: true)
+    end
+
+    it 'handles nil hash configuration value gracefully' do
+      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
+        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
+        def config_text = nil
+
+        def config_text=(_value); end
+      end
+      instance = test_class.new(nil, use_hash_config: { test_conditions: nil })
+      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
+      expect(instance.test_conditions).to be_blank
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # configure_direct in OptionsHandler
+  # ──────────────────────────────────────────────────────────────
+  describe 'configure_direct' do
+    it 'is available as a class method via OptionsHandler' do
+      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_direct)
+    end
+
+    it 'records the direct type in option_types[:direct]' do
+      label_klass = OptionConfigs::ExtraOptionConfigs::Label
+      expect(label_klass.option_types[:direct]).to be_present
+    end
+
+    it 'Fields declares configure_direct type: :array' do
+      fields_klass = OptionConfigs::ExtraOptionConfigs::Fields
+      expect(fields_klass.option_types[:direct]).to include(:fields)
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # Field-keyed BaseConfiguration classes
+  # ──────────────────────────────────────────────────────────────
+  describe 'Field-keyed BaseConfiguration classes' do
+    ExtraOptionConfigsSupport::FIELD_KEYED_CLASSES.each do |class_name|
+      context "#{class_name}" do
+        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
+
+        it 'exists under OptionConfigs::ExtraOptionConfigs namespace' do
+          expect(klass).to be_a Class
+        end
+
+        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+        end
+
+        it 'supports hash-like interface ([], keys, key?, blank?, merge!, symbolize_keys)' do
+          instance = klass.new({})
+          expect(instance).to respond_to(:[], :keys, :key?, :blank?, :merge!, :symbolize_keys)
+        end
+
+        it 'is blank when initialized with empty hash' do
+          instance = klass.new({})
+          expect(instance).to be_blank
+        end
+
+        it 'supports JSON serialization' do
+          instance = klass.new({})
+          expect(JSON.parse(instance.to_json)).to eq({})
+        end
+
+        it 'provides error collection arrays' do
+          instance = klass.new({})
+          expect(instance.config_errors).to eq([])
+          expect(instance.config_warnings).to eq([])
+        end
+      end
+    end
+  end
+
+  # ──────────────────────────────────────────────────────────────
+  # ConfigBase configuration classes exist with correct structure
+  # (CONFIGBASE_CLASSES is empty since all migrated to BaseConfiguration)
+  # ──────────────────────────────────────────────────────────────
+  describe 'ConfigBase configuration classes exist with correct structure' do
+    # CONFIGBASE_CLASSES is empty — all classes converted to BaseConfiguration
+    # This section kept as a placeholder to confirm no ConfigBase classes remain
+    it 'confirms no ConfigBase subclasses remain in the registry' do
+      registry = OptionConfigs::ExtraOptions.config_class_registry
+      registry.each_value do |klass|
+        expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase),
+                                       "#{klass.name} should not inherit from ConfigBase"
+      end
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/save_action_spec.rb b/spec/models/option_configs/extra_option_configs/save_action_spec.rb
new file mode 100644
index 0000000000..f3ed91df0d
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/save_action_spec.rb
@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for SaveAction configuration class.
+# Verifies on_save cascade to on_create/on_update and integration through
+# ExtraOptions initialization (clean_save_action_def behavior).
+RSpec.describe 'ExtraOptionConfigs::SaveAction', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveAction }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:save_action)
+    end
+  end
+
+  describe 'initialization' do
+    it 'cascades on_save to on_create and on_update' do
+      instance = klass.new(on_save: { label: 'Saved' })
+      expect(instance.save_action[:on_create]).to eq(label: 'Saved')
+      expect(instance.save_action[:on_update]).to eq(label: 'Saved')
+    end
+
+    it 'merges on_save into existing on_create and on_update' do
+      instance = klass.new(on_save: { label: 'Default', notify: true }, on_create: { label: 'Created' })
+      expect(instance.save_action[:on_create][:label]).to eq 'Created'
+      expect(instance.save_action[:on_create][:notify]).to eq true
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(label: 'Test')
+      expect(instance.symbolize_keys).to eq(label: 'Test')
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults save_action to a blank SaveAction when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No save action
+      YAML
+      expect(eo.save_action).to be_a OptionConfigs::ExtraOptionConfigs::SaveAction
+      expect(eo.save_action).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Saved
+      YAML
+
+      expect(eo.save_action.save_action[:on_save]).to eq(label: 'Saved')
+      expect(eo.save_action.save_action[:on_create]).to eq(label: 'Saved')
+      expect(eo.save_action.save_action[:on_update]).to eq(label: 'Saved')
+    end
+
+    it 'merges on_save into existing on_create and on_update without overwriting them' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Default
+              notify: true
+            on_create:
+              label: Created
+            on_update:
+              another_key: updated_val
+      YAML
+
+      expect(eo.save_action.save_action[:on_create][:label]).to eq 'Created'
+      expect(eo.save_action.save_action[:on_create][:notify]).to eq true
+      expect(eo.save_action.save_action[:on_update][:label]).to eq 'Default'
+      expect(eo.save_action.save_action[:on_update][:another_key]).to eq 'updated_val'
+    end
+
+    it 'symbolizes save_action keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_action:
+            on_save:
+              label: Test
+      YAML
+      expect(eo.save_action.save_action.keys).to all(be_a Symbol)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb b/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
new file mode 100644
index 0000000000..c61531655c
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for SaveTrigger configuration class.
+# Verifies TriggerTasks typed attributes, on_save cascade,
+# validate callbacks, and integration through ExtraOptions
+# initialization (clean_save_triggers behavior).
+RSpec.describe 'ExtraOptionConfigs::SaveTrigger', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveTrigger }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares all trigger keys as typed attributes with TriggerTasks type' do
+      %i[on_create on_update on_save on_upload on_disable before_save].each do |key|
+        expect(klass.option_types[:typed]).to include(key),
+                                              "Expected option_types[:typed] to include :#{key}"
+        expect(klass.typed_attribute_types[key]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks),
+                                                    "Expected typed_attribute_types[:#{key}] to be TriggerTasks"
+      end
+    end
+  end
+
+  describe 'initialization' do
+    it 'initializes trigger keys as TriggerTasks instances' do
+      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
+      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_create.tasks).to eq([{ notify: { type: 'email' } }])
+    end
+
+    it 'defaults missing trigger keys to blank TriggerTasks' do
+      instance = klass.new({})
+      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_create).to be_blank
+      expect(instance.on_upload).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.on_upload).to be_blank
+    end
+
+    it 'supports hash-like bracket access for trigger keys' do
+      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
+      expect(instance[:on_create]).to be_a(Array)
+    end
+
+    it 'cascades on_save into on_create and on_update' do
+      instance = klass.new(on_save: { notify: { type: 'email' } })
+      expect(instance.on_create.tasks).to be_an Array
+      expect(instance.on_create.tasks.length).to eq 1
+      expect(instance.on_update.tasks).to be_an Array
+      expect(instance.on_update.tasks.length).to eq 1
+    end
+
+    it 'appends on_save to existing on_create and on_update' do
+      instance = klass.new(
+        on_save: { notify: { type: 'email' } },
+        on_create: { create_action: { type: 'special' } }
+      )
+      expect(instance.on_create.tasks).to be_an Array
+      expect(instance.on_create.tasks.length).to eq 2
+      expect(instance.on_update.tasks).to be_an Array
+      expect(instance.on_update.tasks.length).to eq 1
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'validates keys against ValidSaveTriggerTriggers' do
+      instance = klass.new(on_invalid_trigger: { something: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :save_trigger }
+      expect(err).to be_present
+    end
+
+    it 'with invalid keys has errors on :save_trigger' do
+      instance = klass.new(on_invalid_trigger: { something: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :save_trigger }
+      expect(err).to be_present
+      expect(err[:message]).to match(/invalid keys/)
+    end
+
+    it 'with valid keys has no validation errors' do
+      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
+      expect(instance.config_errors).to be_empty
+    end
+
+    it 'with invalid keys has ActiveModel errors' do
+      instance = klass.new(on_invalid_trigger: { something: true })
+      expect(instance.errors[:save_trigger]).not_to be_empty
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults save_trigger to a SaveTrigger with blank TriggerTasks' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No save triggers
+      YAML
+
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger[:on_upload]).to be_a Hash
+      expect(eo.save_trigger[:on_upload]).to be_blank
+      expect(eo.save_trigger[:on_disable]).to be_a Hash
+      expect(eo.save_trigger[:on_disable]).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as array defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+
+      expect(eo.save_trigger[:on_create]).to be_an Array
+      expect(eo.save_trigger[:on_update]).to be_an Array
+      expect(eo.save_trigger[:on_create].length).to eq 1
+      expect(eo.save_trigger[:on_update].length).to eq 1
+    end
+
+    it 'appends on_save triggers to existing on_create and on_update' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+            on_create:
+              create_action:
+                type: special
+      YAML
+
+      expect(eo.save_trigger[:on_create]).to be_an Array
+      expect(eo.save_trigger[:on_create].length).to eq 2
+      expect(eo.save_trigger[:on_update]).to be_an Array
+      expect(eo.save_trigger[:on_update].length).to eq 1
+    end
+
+    it 'reports an error for invalid trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_invalid_trigger:
+              something: true
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :save_trigger }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes save_trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger.on_create).to be_a OptionConfigs::ExtraOptionConfigs::TriggerTasks
+    end
+
+    it 'is stored directly as a SaveTrigger instance' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_save:
+              notify:
+                type: email
+      YAML
+
+      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
+      expect(eo.save_trigger[:on_create]).to be_a Array
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/set_variable_spec.rb b/spec/models/option_configs/extra_option_configs/set_variable_spec.rb
new file mode 100644
index 0000000000..897cad31ba
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/set_variable_spec.rb
@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for SetVariable configuration class.
+# Verifies configure_direct with type :array, entry validation,
+# validate callbacks, and integration through ExtraOptions initialization
+# (clean_set_variables_def behavior).
+RSpec.describe 'ExtraOptionConfigs::SetVariable', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::SetVariable }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :array' do
+      expect(klass.option_types[:direct]).to include(:set_variables)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores valid array entries' do
+      instance = klass.new([{ name: 'var1', value: 'val1' }])
+      expect(instance.set_variables).to be_an Array
+      expect(instance.set_variables.length).to eq 1
+      expect(instance.set_variables[0][:name]).to eq 'var1'
+    end
+
+    it 'reports error when value is not an array' do
+      instance = klass.new(name: 'var1', value: 'val1')
+      expect(instance.config_errors).not_to be_empty
+    end
+
+    it 'filters out invalid entries' do
+      instance = klass.new([{ name: 'valid', value: 'val' }, { no_name: 'invalid' }])
+      expect(instance.set_variables.length).to eq 1
+    end
+
+    it 'returns blank when initialized with nil' do
+      instance = klass.new(nil)
+      expect(instance).to be_blank
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'with non-array input has errors on :set_variables' do
+      instance = klass.new({ name: 'var1', value: 'val1' })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :set_variables }
+      expect(err).to be_present
+      expect(err[:message]).to match(/must be an array/)
+    end
+
+    it 'with invalid entries has errors on :set_variables' do
+      instance = klass.new([{ bad_key: 'test' }])
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :set_variables }
+      expect(err).to be_present
+      expect(err[:message]).to match(/must have 'name' and 'value' keys/)
+    end
+
+    it 'with valid entries has no validation errors' do
+      instance = klass.new([{ name: 'v', value: 'x' }])
+      expect(instance.config_errors).to be_empty
+    end
+
+    it 'with non-array has ActiveModel errors' do
+      instance = klass.new({ name: 'var1', value: 'val1' })
+      expect(instance.errors[:set_variables]).not_to be_empty
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults set_variables to nil when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No variables
+      YAML
+      expect(eo.set_variables).to be_nil
+    end
+
+    it 'preserves valid set_variables array entries' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            - name: var1
+              value: val1
+            - name: var2
+              value: val2
+              if:
+                always: true
+      YAML
+
+      expect(eo.set_variables).to be_an Array
+      expect(eo.set_variables.length).to eq 2
+      expect(eo.set_variables[0][:name]).to eq 'var1'
+      expect(eo.set_variables[0][:value]).to eq 'val1'
+      expect(eo.set_variables[1][:name]).to eq 'var2'
+      expect(eo.set_variables[1][:if]).to be_present
+    end
+
+    it 'reports an error and empties when set_variables is not an array' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            name: var1
+            value: val1
+      YAML
+
+      expect(eo.set_variables).to eq []
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :set_variables }
+      expect(err).to be_present
+    end
+
+    it 'filters out invalid entries missing name or value keys' do
+      eo = config_for(<<~YAML)
+        default:
+          set_variables:
+            - name: valid_var
+              value: valid_val
+            - no_name_key: invalid
+      YAML
+
+      expect(eo.set_variables).to be_an Array
+      expect(eo.set_variables.length).to eq 1
+      expect(eo.set_variables[0][:name]).to eq 'valid_var'
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/show_if_spec.rb b/spec/models/option_configs/extra_option_configs/show_if_spec.rb
new file mode 100644
index 0000000000..29d7546322
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/show_if_spec.rb
@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ShowIf configuration class (field-keyed BaseConfiguration).
+# Verifies condition hash storage and integration through
+# ExtraOptions initialization (clean_show_if_def behavior).
+RSpec.describe 'ExtraOptionConfigs::ShowIf', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::ShowIf }
+
+  describe 'initialization' do
+    it 'stores arbitrary condition hashes directly' do
+      instance = klass.new(field1: { other_field: 'value' })
+      expect(instance[:field1]).to eq(other_field: 'value')
+    end
+
+    it 'symbolize_keys returns plain Hash of condition hashes' do
+      instance = klass.new(field1: { other_field: 'value' })
+      expect(instance.symbolize_keys).to eq(field1: { other_field: 'value' })
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults show_if to a blank ShowIf instance when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No show_if
+      YAML
+      expect(eo.show_if).to be_blank
+    end
+
+    it 'preserves explicitly set show_if conditions and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          show_if:
+            test2:
+              test1: some_value
+      YAML
+
+      expect(eo.show_if).to have_key(:test2)
+      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
+    end
+
+    it 'does not overwrite existing show_if when show_if_condition_strings provides a duplicate' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+            - test2
+          show_if:
+            test2:
+              test1: existing_value
+          show_if_condition_strings:
+            test2: "[test1] = 'other_value'"
+      YAML
+
+      expect(eo.show_if[:test2]).to eq(test1: 'existing_value')
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/trigger_tasks_spec.rb b/spec/models/option_configs/extra_option_configs/trigger_tasks_spec.rb
new file mode 100644
index 0000000000..c547b85d8d
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/trigger_tasks_spec.rb
@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for TriggerTasks configuration class.
+# TriggerTasks is a utility class used by SaveTrigger, BatchTrigger,
+# and ConfigTrigger to store trigger task data (either Hash or Array).
+RSpec.describe 'ExtraOptionConfigs::TriggerTasks', type: :model do
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::TriggerTasks }
+
+  describe 'class structure' do
+    it 'exists under ExtraOptionConfigs namespace' do
+      expect(klass).to be_a Class
+    end
+
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:tasks)
+      expect(klass.direct_types[:tasks]).to eq(:hash)
+    end
+  end
+
+  describe 'Hash initialization' do
+    it 'stores entire hash as single tasks attribute' do
+      instance = klass.new(notify: { type: 'email' }, update_this: { field: 'val' })
+      expect(instance.tasks).to eq(notify: { type: 'email' }, update_this: { field: 'val' })
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'handles nil initialization' do
+      instance = klass.new(nil)
+      expect(instance.tasks).to eq({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys on initialization' do
+      instance = klass.new('notify' => { 'type' => 'email' })
+      expect(instance.tasks).to have_key(:notify)
+    end
+
+    it 'supports symbolize_keys for backward compatibility' do
+      instance = klass.new(notify: { type: 'email' })
+      expect(instance.symbolize_keys).to eq(notify: { type: 'email' })
+    end
+  end
+
+  describe 'Array initialization' do
+    it 'stores array value as tasks when initialized with an array' do
+      arr = [{ notify: { type: 'email' } }, { update_this: { field: 'val' } }]
+      instance = klass.new(arr)
+      expect(instance.tasks).to eq(arr)
+    end
+
+    it 'returns not blank when initialized with a non-empty array' do
+      instance = klass.new([{ notify: { type: 'email' } }])
+      expect(instance).not_to be_blank
+    end
+
+    it 'returns blank when initialized with an empty array' do
+      instance = klass.new([])
+      expect(instance).to be_blank
+    end
+
+    it 'symbolize_keys returns the array as-is when tasks is an array' do
+      arr = [{ notify: { type: 'email' } }]
+      instance = klass.new(arr)
+      expect(instance.symbolize_keys).to eq(arr)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/valid_if_spec.rb b/spec/models/option_configs/extra_option_configs/valid_if_spec.rb
new file mode 100644
index 0000000000..4927b25508
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/valid_if_spec.rb
@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ValidIf configuration class.
+# Verifies on_save cascade, key validation against ValidValidIfTriggers,
+# validate callbacks, and integration through ExtraOptions initialization
+# (clean_valid_if_def behavior).
+RSpec.describe 'ExtraOptionConfigs::ValidIf', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::ValidIf }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:valid_if)
+    end
+  end
+
+  describe 'initialization' do
+    it 'cascades on_save to on_create and on_update' do
+      instance = klass.new(on_save: { all: { this: { test1: 'is not null' } } })
+      expect(instance.valid_if[:on_create]).to eq(instance.valid_if[:on_save])
+      expect(instance.valid_if[:on_update]).to eq(instance.valid_if[:on_save])
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(on_save: { always: true })
+      expect(instance.symbolize_keys).to have_key(:on_save)
+    end
+  end
+
+  describe 'validate callbacks' do
+    it 'validates keys against ValidValidIfTriggers' do
+      instance = klass.new(on_invalid_key: { always: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :valid_if }
+      expect(err).to be_present
+    end
+
+    it 'with invalid keys has errors on :valid_if' do
+      instance = klass.new(on_invalid_key: { always: true })
+      expect(instance.config_errors).not_to be_empty
+      err = instance.config_errors.find { |e| e[:type] == :valid_if }
+      expect(err).to be_present
+      expect(err[:message]).to match(/invalid keys/)
+    end
+
+    it 'with valid keys has no validation errors' do
+      instance = klass.new(on_save: { all: { this: { field: 'is not null' } } })
+      expect(instance.config_errors).to be_empty
+    end
+
+    it 'with invalid keys has ActiveModel errors' do
+      instance = klass.new(on_invalid_key: { always: true })
+      expect(instance.errors[:valid_if]).not_to be_empty
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults valid_if to a blank ValidIf when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No valid_if
+      YAML
+      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
+      expect(eo.valid_if).to be_blank
+    end
+
+    it 'cascades on_save to on_create and on_update as defaults' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+      YAML
+
+      expect(eo.valid_if.valid_if[:on_save]).to be_present
+      expect(eo.valid_if.valid_if[:on_create]).to eq eo.valid_if.valid_if[:on_save]
+      expect(eo.valid_if.valid_if[:on_update]).to eq eo.valid_if.valid_if[:on_save]
+    end
+
+    it 'merges on_save into existing on_create and on_update' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+            on_create:
+              all:
+                this:
+                  test2: is not null
+      YAML
+
+      expect(eo.valid_if.valid_if[:on_create]).to have_key(:all)
+    end
+
+    it 'reports an error for invalid trigger keys' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_invalid_key:
+              always: true
+      YAML
+
+      expect(eo.config_errors).not_to be_empty
+      err = eo.config_errors.find { |e| e[:type] == :valid_if }
+      expect(err).to be_present
+    end
+
+    it 'symbolizes valid_if keys' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              always: true
+      YAML
+      expect(eo.valid_if.valid_if.keys).to all(be_a Symbol)
+    end
+
+    it 'is stored directly as a ValidIf BaseConfiguration instance' do
+      eo = config_for(<<~YAML)
+        default:
+          valid_if:
+            on_save:
+              all:
+                this:
+                  test1: is not null
+      YAML
+
+      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
+      expect(eo.valid_if[:on_create]).to be_present
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/validations_spec.rb b/spec/models/option_configs/extra_option_configs/validations_spec.rb
new file mode 100644
index 0000000000..274e899986
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/validations_spec.rb
@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ActiveModel::Validations integration with BaseConfiguration.
+# Verifies the run_validations bridge, TypedAttributeValidator,
+# validates declarations, and error bridging into config_errors.
+RSpec.describe 'ExtraOptionConfigs ActiveModel::Validations integration', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  describe 'ActiveModel::Validations integration' do
+    it 'errors is ActiveModel::Errors, not a plain Array' do
+      instance = OptionConfigs::ExtraOptionConfigs::BaseConfiguration.new({})
+      expect(instance.errors).to be_a(ActiveModel::Errors)
+    end
+
+    it 'validates declarations produce config_errors when value is blank' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_direct :test_attr, type: :string
+        validates :test_attr, presence: true
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).not_to be_empty
+      messages = instance.config_errors.map { |e| e[:message] }
+      expect(messages.join(' ')).to match(/test_attr.*blank|can't be blank/i)
+    end
+
+    it 'valid config produces no config_errors from validates' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_direct :test_attr, type: :string
+        validates :test_attr, presence: true
+
+        def setup_named_configurations
+          self.test_attr = 'a valid value'
+        end
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).to be_empty
+    end
+
+    it 'TypedAttributeValidator catches wrong type' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          setup_all_options_typed(hash_configuration)
+        end
+      end
+
+      instance = test_class.new({})
+      # Manually assign wrong type after initialization
+      instance.my_typed = 'wrong'
+      instance.valid?
+      expect(instance.errors[:my_typed]).not_to be_empty
+      expect(instance.errors[:my_typed].join(' ')).to match(/must be a.*TriggerTasks.*got String/)
+    end
+
+    it 'TypedAttributeValidator passes correct type' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          setup_all_options_typed(hash_configuration)
+        end
+      end
+
+      instance = test_class.new(my_typed: { notify: { type: 'email' } })
+      expect(instance.my_typed).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
+      expect(instance.valid?).to be true
+      expect(instance.errors[:my_typed]).to be_empty
+    end
+
+    it 'TypedAttributeValidator allows nil' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
+        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
+        validates :my_typed, 'validates/typed_attribute': true
+
+        def setup_named_configurations
+          # Don't set my_typed — leave it nil
+        end
+      end
+
+      instance = test_class.new({})
+      expect(instance.my_typed).to be_nil
+      expect(instance.valid?).to be true
+      expect(instance.errors[:my_typed]).to be_empty
+    end
+
+    it 'full integration: BatchTrigger subclass with validates produces config_errors on empty config' do
+      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BatchTrigger) do
+        validates :on_record, presence: true
+      end
+
+      instance = test_class.new({})
+      expect(instance.config_errors).not_to be_empty
+      messages = instance.config_errors.map { |e| e[:message] }
+      expect(messages.join(' ')).to match(/on_record.*blank|can't be blank/i)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/view_options_spec.rb b/spec/models/option_configs/extra_option_configs/view_options_spec.rb
new file mode 100644
index 0000000000..363fd61f22
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/view_options_spec.rb
@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for ViewOptions configuration class.
+# Verifies configure_direct with type :hash and integration through
+# ExtraOptions initialization (clean_view_options_def behavior).
+RSpec.describe 'ExtraOptionConfigs::ViewOptions', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::ViewOptions }
+
+  describe 'class structure' do
+    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
+      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
+    end
+
+    it 'does not inherit from ConfigBase' do
+      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    end
+
+    it 'declares configure_direct with type :hash' do
+      expect(klass.option_types[:direct]).to include(:view_options)
+    end
+  end
+
+  describe 'initialization' do
+    it 'stores entire hash as single attribute' do
+      instance = klass.new(data_attribute: 'field_1', show_embedded: true)
+      expect(instance.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
+    end
+
+    it 'returns blank when initialized with empty hash' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'symbolizes keys for backward compatibility' do
+      instance = klass.new(data_attribute: 'test')
+      expect(instance.symbolize_keys).to eq(data_attribute: 'test')
+    end
+  end
+
+  describe 'ExtraOptions integration' do
+    it 'defaults view_options to a blank ViewOptions when not specified' do
+      eo = config_for(<<~YAML)
+        default:
+          label: No view options
+      YAML
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options).to be_blank
+    end
+
+    it 'preserves view_options and symbolizes keys' do
+      eo = config_for(<<~YAML)
+        default:
+          view_options:
+            data_attribute: field_1
+            show_embedded: true
+      YAML
+      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
+      expect(eo.view_options.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs_spec.rb b/spec/models/option_configs/extra_option_configs_spec.rb
deleted file mode 100644
index 1e9118b3c4..0000000000
--- a/spec/models/option_configs/extra_option_configs_spec.rb
+++ /dev/null
@@ -1,2099 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails_helper'
-require './db/table_generators/dynamic_models_table'
-
-# Phase 2 of issue #986: Verify configuration classes for ExtraOptions clean methods.
-# Each top-level configuration area from ExtraOptions has a dedicated configuration class
-# under OptionConfigs::ExtraOptionConfigs:: namespace. These tests verify:
-# - All configuration classes exist with correct inheritance
-# - Each class declares its managed attributes
-# - ExtraOptions stores config instances after initialization
-# - Config instance attribute values match ExtraOptions attribute values
-# - ActiveModel::Validations is available on all config classes for reflection
-# - CaptionBefore uses BaseConfiguration/NamedConfiguration pattern with hash compatibility
-RSpec.describe 'ExtraOptionConfigs configuration classes', type: :model do
-  include MasterSupport
-  include ModelSupport
-  include DynamicModelSupport
-
-  before(:each) do
-    create_admin
-    create_user
-    setup_access :trackers
-    setup_access :tracker_histories
-    @dm = generate_test_dynamic_model
-    setup_access :dynamic_model__test_created_by_recs, user: @user
-  end
-
-  # Helper: update the DynamicModel with given YAML options and return the first option config
-  def config_for(yaml)
-    @dm.update!(options: yaml, current_admin: @admin)
-    @dm.option_configs.first
-  end
-
-  # All expected config classes with their managed attributes.
-  # Registry key must match the ExtraOptions attribute name.
-  # Class names are singular (SaveTrigger not SaveTriggers).
-  # AccessIf is split into CreatableIf, EditableIf, ShowableIf.
-  EXPECTED_CONFIG_CLASSES = {
-    fields: :Fields,
-    label: :Label,
-    caption_before: :CaptionBefore,
-    dialog_before: :DialogBefore,
-    labels: :Labels,
-    show_if: :ShowIf,
-    save_action: :SaveAction,
-    view_options: :ViewOptions,
-    db_configs: :DbConfigs,
-    creatable_if: :CreatableIf,
-    editable_if: :EditableIf,
-    showable_if: :ShowableIf,
-    valid_if: :ValidIf,
-    filestore: :Filestore,
-    field_options: :FieldOptions,
-    embed: :Embed,
-    references: :References,
-    save_trigger: :SaveTrigger,
-    batch_trigger: :BatchTrigger,
-    config_trigger: :ConfigTrigger,
-    preset_fields: :PresetFields,
-    set_variables: :SetVariable,
-    field_configs: :FieldConfigs
-  }.freeze
-
-  # ──────────────────────────────────────────────────────────────
-  # ConfigBase
-  # ──────────────────────────────────────────────────────────────
-  describe 'OptionConfigs::ExtraOptionConfigs::ConfigBase' do
-    it 'exists as a class' do
-      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to be_a Class
-    end
-
-    it 'includes ActiveModel::Validations' do
-      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase.ancestors).to include(ActiveModel::Validations)
-    end
-
-    it 'provides managed_attributes class method' do
-      expect(OptionConfigs::ExtraOptionConfigs::ConfigBase).to respond_to(:managed_attributes)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Registry key alignment and config_class_attributes
-  # ──────────────────────────────────────────────────────────────
-  describe 'config_class_registry and config_class_attributes' do
-    it 'config_class_registry keys match ExtraOptions attribute names' do
-      registry = OptionConfigs::ExtraOptions.config_class_registry
-      EXPECTED_CONFIG_CLASSES.each_key do |attr_key|
-        expect(registry).to have_key(attr_key),
-                            "Expected config_class_registry to have key :#{attr_key}"
-      end
-    end
-
-    it 'registry class names are singular (no trailing s on Triggers/Variables)' do
-      registry = OptionConfigs::ExtraOptions.config_class_registry
-      # These classes should exist with singular names
-      expect(registry[:save_trigger].name).to include('SaveTrigger')
-      expect(registry[:save_trigger].name).not_to include('SaveTriggers')
-      expect(registry[:batch_trigger].name).to include('BatchTrigger')
-      expect(registry[:batch_trigger].name).not_to include('BatchTriggers')
-      expect(registry[:config_trigger].name).to include('ConfigTrigger')
-      expect(registry[:config_trigger].name).not_to include('ConfigTriggers')
-      expect(registry[:set_variables].name).to include('SetVariable')
-    end
-
-    it 'AccessIf is split into CreatableIf, EditableIf, ShowableIf' do
-      registry = OptionConfigs::ExtraOptions.config_class_registry
-      expect(registry).not_to have_key(:access_if)
-      expect(registry).to have_key(:creatable_if)
-      expect(registry).to have_key(:editable_if)
-      expect(registry).to have_key(:showable_if)
-    end
-
-    it 'provides config_class_attributes derived from registry keys' do
-      attrs = OptionConfigs::ExtraOptions.config_class_attributes
-      expect(attrs).to be_an Array
-      EXPECTED_CONFIG_CLASSES.each_key do |key|
-        expect(attrs).to include(key),
-                         "Expected config_class_attributes to include :#{key}"
-      end
-    end
-
-    it 'base_key_attributes does not include config class attributes' do
-      base = OptionConfigs::ExtraOptions.base_key_attributes
-      config_attrs = OptionConfigs::ExtraOptions.config_class_attributes
-      overlap = base & config_attrs
-      expect(overlap).to be_empty,
-                         "base_key_attributes should not overlap config_class_attributes, but found: #{overlap}"
-    end
-
-    it 'key_attributes includes both base and config class attributes' do
-      all = OptionConfigs::ExtraOptions.key_attributes
-      base = OptionConfigs::ExtraOptions.base_key_attributes
-      config = OptionConfigs::ExtraOptions.config_class_attributes
-      expect(all).to include(*base)
-      expect(all).to include(*config)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # configure_typed_attribute in OptionsHandler
-  # ──────────────────────────────────────────────────────────────
-  describe 'configure_typed_attribute' do
-    it 'is available as a class method via OptionsHandler' do
-      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_typed_attribute)
-    end
-
-    it 'registers the attribute in option_types[:typed]' do
-      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
-        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
-        def config_text = nil
-      end
-      expect(test_class.option_types[:typed]).to include(:test_conditions)
-    end
-
-    it 'stores the type class reference in typed_attribute_types' do
-      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
-        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
-        def config_text = nil
-      end
-      expect(test_class.typed_attribute_types[:test_conditions]).to eq(OptionConfigs::ExtraOptionConfigs::IfCondition)
-    end
-
-    it 'auto-initializes the attribute from hash configuration' do
-      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
-        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
-        def config_text = nil
-
-        def config_text=(_value); end
-      end
-      instance = test_class.new(nil, use_hash_config: { test_conditions: { always: true } })
-      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
-      expect(instance.test_conditions.conditions).to eq(always: true)
-    end
-
-    it 'handles nil hash configuration value gracefully' do
-      test_class = Class.new(OptionConfigs::BaseNamedConfiguration) do
-        configure_typed_attribute :test_conditions, type: OptionConfigs::ExtraOptionConfigs::IfCondition
-        def config_text = nil
-
-        def config_text=(_value); end
-      end
-      instance = test_class.new(nil, use_hash_config: { test_conditions: nil })
-      expect(instance.test_conditions).to be_a(OptionConfigs::ExtraOptionConfigs::IfCondition)
-      expect(instance.test_conditions).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # IfCondition configuration class
-  # ──────────────────────────────────────────────────────────────
-  describe 'IfCondition' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::IfCondition }
-
-    it 'exists under ExtraOptionConfigs namespace' do
-      expect(klass).to be_a Class
-    end
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:conditions)
-      expect(klass.direct_types[:conditions]).to eq(:hash)
-    end
-
-    it 'stores entire hash as single conditions attribute' do
-      instance = klass.new(always: true, user_is_creator: true)
-      expect(instance.conditions).to eq(always: true, user_is_creator: true)
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'returns not blank when initialized with data' do
-      instance = klass.new(always: true)
-      expect(instance).not_to be_blank
-    end
-
-    it 'symbolizes keys on initialization' do
-      instance = klass.new('always' => true)
-      expect(instance.conditions).to have_key(:always)
-    end
-
-    it 'handles nil initialization' do
-      instance = klass.new(nil)
-      expect(instance.conditions).to eq({})
-      expect(instance).to be_blank
-    end
-
-    it 'supports symbolize_keys for backward compatibility' do
-      instance = klass.new(always: true, never: false)
-      expect(instance.symbolize_keys).to eq(always: true, never: false)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # TriggerTasks configuration class
-  # ──────────────────────────────────────────────────────────────
-  describe 'TriggerTasks' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::TriggerTasks }
-
-    it 'exists under ExtraOptionConfigs namespace' do
-      expect(klass).to be_a Class
-    end
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:tasks)
-      expect(klass.direct_types[:tasks]).to eq(:hash)
-    end
-
-    it 'stores entire hash as single tasks attribute' do
-      instance = klass.new(notify: { type: 'email' }, update_this: { field: 'val' })
-      expect(instance.tasks).to eq(notify: { type: 'email' }, update_this: { field: 'val' })
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'handles nil initialization' do
-      instance = klass.new(nil)
-      expect(instance.tasks).to eq({})
-      expect(instance).to be_blank
-    end
-
-    it 'symbolizes keys on initialization' do
-      instance = klass.new('notify' => { 'type' => 'email' })
-      expect(instance.tasks).to have_key(:notify)
-    end
-
-    it 'supports symbolize_keys for backward compatibility' do
-      instance = klass.new(notify: { type: 'email' })
-      expect(instance.symbolize_keys).to eq(notify: { type: 'email' })
-    end
-
-    # Array support for save_trigger values (on_create, on_update, etc.)
-    it 'stores array value as tasks when initialized with an array' do
-      arr = [{ notify: { type: 'email' } }, { update_this: { field: 'val' } }]
-      instance = klass.new(arr)
-      expect(instance.tasks).to eq(arr)
-    end
-
-    it 'returns not blank when initialized with a non-empty array' do
-      instance = klass.new([{ notify: { type: 'email' } }])
-      expect(instance).not_to be_blank
-    end
-
-    it 'returns blank when initialized with an empty array' do
-      instance = klass.new([])
-      expect(instance).to be_blank
-    end
-
-    it 'symbolize_keys returns the array as-is when tasks is an array' do
-      arr = [{ notify: { type: 'email' } }]
-      instance = klass.new(arr)
-      expect(instance.symbolize_keys).to eq(arr)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # BatchTrigger converted to BaseConfiguration with TriggerTasks
-  # ──────────────────────────────────────────────────────────────
-  describe 'BatchTrigger (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::BatchTrigger }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares on_record as a typed attribute with TriggerTasks type' do
-      expect(klass.option_types[:typed]).to include(:on_record)
-      expect(klass.typed_attribute_types[:on_record]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-    end
-
-    it 'initializes on_record as a TriggerTasks instance from hash' do
-      instance = klass.new(on_record: { notify: { type: 'email' } })
-      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_record.tasks).to eq(notify: { type: 'email' })
-    end
-
-    it 'initializes on_record as blank TriggerTasks when not provided' do
-      instance = klass.new({})
-      expect(instance.on_record).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_record).to be_blank
-    end
-
-    it 'supports hash-like bracket access for on_record' do
-      instance = klass.new(on_record: { action: 'process' })
-      expect(instance[:on_record]).to be_a(Hash)
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # configure_direct in OptionsHandler
-  # ──────────────────────────────────────────────────────────────
-  describe 'configure_direct' do
-    it 'is available as a class method via OptionsHandler' do
-      expect(OptionConfigs::BaseNamedConfiguration).to respond_to(:configure_direct)
-    end
-
-    it 'records the direct type in option_types[:direct]' do
-      # Label uses configure_direct type: :string
-      label_klass = OptionConfigs::ExtraOptionConfigs::Label
-      expect(label_klass.option_types[:direct]).to be_present
-    end
-
-    it 'Fields declares configure_direct type: :array' do
-      fields_klass = OptionConfigs::ExtraOptionConfigs::Fields
-      expect(fields_klass.option_types[:direct]).to include(:fields)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # CreatableIf, EditableIf, ShowableIf (split from AccessIf)
-  # Note: detailed conversion tests are in 'if_condition classes (converted to BaseConfiguration)' section above
-  # ──────────────────────────────────────────────────────────────
-  describe 'if_condition classes (split from AccessIf)' do
-    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
-      context "#{class_name}" do
-        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
-
-        it 'exists under ExtraOptionConfigs namespace' do
-          expect(klass).to be_a Class
-        end
-
-        it 'uses configure_direct with type :hash' do
-          expect(klass.option_types[:direct]).to be_present
-        end
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # SaveTrigger converted to BaseConfiguration with TriggerTasks
-  # ──────────────────────────────────────────────────────────────
-  describe 'SaveTrigger (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveTrigger }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares all trigger keys as typed attributes with TriggerTasks type' do
-      %i[on_create on_update on_save on_upload on_disable before_save].each do |key|
-        expect(klass.option_types[:typed]).to include(key),
-                                              "Expected option_types[:typed] to include :#{key}"
-        expect(klass.typed_attribute_types[key]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks),
-                                                    "Expected typed_attribute_types[:#{key}] to be TriggerTasks"
-      end
-    end
-
-    it 'initializes trigger keys as TriggerTasks instances' do
-      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
-      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_create.tasks).to eq([{ notify: { type: 'email' } }])
-    end
-
-    it 'defaults missing trigger keys to blank TriggerTasks' do
-      instance = klass.new({})
-      expect(instance.on_create).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_create).to be_blank
-      expect(instance.on_upload).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_upload).to be_blank
-    end
-
-    it 'supports hash-like bracket access for trigger keys' do
-      instance = klass.new(on_create: [{ notify: { type: 'email' } }])
-      expect(instance[:on_create]).to be_a(Array)
-    end
-
-    it 'cascades on_save into on_create and on_update' do
-      instance = klass.new(on_save: { notify: { type: 'email' } })
-      expect(instance.on_create.tasks).to be_an Array
-      expect(instance.on_create.tasks.length).to eq 1
-      expect(instance.on_update.tasks).to be_an Array
-      expect(instance.on_update.tasks.length).to eq 1
-    end
-
-    it 'appends on_save to existing on_create and on_update' do
-      instance = klass.new(
-        on_save: { notify: { type: 'email' } },
-        on_create: { create_action: { type: 'special' } }
-      )
-      expect(instance.on_create.tasks).to be_an Array
-      expect(instance.on_create.tasks.length).to eq 2
-      expect(instance.on_update.tasks).to be_an Array
-      expect(instance.on_update.tasks.length).to eq 1
-    end
-
-    it 'validates keys against ValidSaveTriggerTriggers' do
-      instance = klass.new(on_invalid_trigger: { something: true })
-      expect(instance.config_errors).not_to be_empty
-      err = instance.config_errors.find { |e| e[:type] == :save_trigger }
-      expect(err).to be_present
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ViewOptions converted to BaseConfiguration (simple direct hash)
-  # ──────────────────────────────────────────────────────────────
-  describe 'ViewOptions (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::ViewOptions }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:view_options)
-    end
-
-    it 'stores entire hash as single attribute' do
-      instance = klass.new(data_attribute: 'field_1', show_embedded: true)
-      expect(instance.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'symbolizes keys for backward compatibility' do
-      instance = klass.new(data_attribute: 'test')
-      expect(instance.symbolize_keys).to eq(data_attribute: 'test')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Filestore converted to BaseConfiguration (simple direct hash)
-  # ──────────────────────────────────────────────────────────────
-  describe 'Filestore (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::Filestore }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:filestore)
-    end
-
-    it 'stores entire hash as single attribute' do
-      instance = klass.new(container: { path: '/test' })
-      expect(instance.filestore).to eq(container: { path: '/test' })
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'symbolizes keys for backward compatibility' do
-      instance = klass.new(container: {})
-      expect(instance.symbolize_keys).to eq(container: {})
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ConfigTrigger converted to BaseConfiguration
-  # ──────────────────────────────────────────────────────────────
-  describe 'ConfigTrigger (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::ConfigTrigger }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares on_define as a typed attribute with TriggerTasks type' do
-      expect(klass.option_types[:typed]).to include(:on_define)
-      expect(klass.typed_attribute_types[:on_define]).to eq(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-    end
-
-    it 'wraps non-array on_define in an array' do
-      instance = klass.new(on_define: { action: 'do_something' })
-      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_define.tasks).to be_an Array
-      expect(instance.on_define.tasks.length).to eq 1
-    end
-
-    it 'preserves array on_define' do
-      instance = klass.new(on_define: [{ action: 'first' }, { action: 'second' }])
-      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_define.tasks).to be_an Array
-      expect(instance.on_define.tasks.length).to eq 2
-    end
-
-    it 'defaults on_define to blank TriggerTasks when not provided' do
-      instance = klass.new({})
-      expect(instance.on_define).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.on_define).to be_blank
-    end
-
-    it 'supports hash-like bracket access' do
-      instance = klass.new(on_define: [{ action: 'test' }])
-      expect(instance[:on_define]).to be_a(Array)
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # SaveAction converted to BaseConfiguration (simple direct hash with cascade)
-  # ──────────────────────────────────────────────────────────────
-  describe 'SaveAction (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::SaveAction }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:save_action)
-    end
-
-    it 'cascades on_save to on_create and on_update' do
-      instance = klass.new(on_save: { label: 'Saved' })
-      expect(instance.save_action[:on_create]).to eq(label: 'Saved')
-      expect(instance.save_action[:on_update]).to eq(label: 'Saved')
-    end
-
-    it 'merges on_save into existing on_create and on_update' do
-      instance = klass.new(on_save: { label: 'Default', notify: true }, on_create: { label: 'Created' })
-      expect(instance.save_action[:on_create][:label]).to eq 'Created'
-      expect(instance.save_action[:on_create][:notify]).to eq true
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'symbolizes keys for backward compatibility' do
-      instance = klass.new(label: 'Test')
-      expect(instance.symbolize_keys).to eq(label: 'Test')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ValidIf converted to BaseConfiguration (direct hash with cascade + validation)
-  # ──────────────────────────────────────────────────────────────
-  describe 'ValidIf (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::ValidIf }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:valid_if)
-    end
-
-    it 'cascades on_save to on_create and on_update' do
-      instance = klass.new(on_save: { all: { this: { test1: 'is not null' } } })
-      expect(instance.valid_if[:on_create]).to eq(instance.valid_if[:on_save])
-      expect(instance.valid_if[:on_update]).to eq(instance.valid_if[:on_save])
-    end
-
-    it 'validates keys against ValidValidIfTriggers' do
-      instance = klass.new(on_invalid_key: { always: true })
-      expect(instance.config_errors).not_to be_empty
-      err = instance.config_errors.find { |e| e[:type] == :valid_if }
-      expect(err).to be_present
-    end
-
-    it 'returns blank when initialized with empty hash' do
-      instance = klass.new({})
-      expect(instance).to be_blank
-    end
-
-    it 'symbolizes keys for backward compatibility' do
-      instance = klass.new(on_save: { always: true })
-      expect(instance.symbolize_keys).to have_key(:on_save)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # SetVariable converted to BaseConfiguration (direct array with validation)
-  # ──────────────────────────────────────────────────────────────
-  describe 'SetVariable (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::SetVariable }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :array' do
-      expect(klass.option_types[:direct]).to include(:set_variables)
-    end
-
-    it 'stores valid array entries' do
-      instance = klass.new([{ name: 'var1', value: 'val1' }])
-      expect(instance.set_variables).to be_an Array
-      expect(instance.set_variables.length).to eq 1
-      expect(instance.set_variables[0][:name]).to eq 'var1'
-    end
-
-    it 'reports error when value is not an array' do
-      instance = klass.new(name: 'var1', value: 'val1')
-      expect(instance.config_errors).not_to be_empty
-    end
-
-    it 'filters out invalid entries' do
-      instance = klass.new([{ name: 'valid', value: 'val' }, { no_name: 'invalid' }])
-      expect(instance.set_variables.length).to eq 1
-    end
-
-    it 'returns blank when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Fields (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'Fields (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::Fields }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :array' do
-      expect(klass.option_types[:direct]).to include(:fields)
-    end
-
-    it 'stores the array as fields attribute' do
-      instance = klass.new(%w[field1 field2])
-      expect(instance.fields).to eq %w[field1 field2]
-    end
-
-    it 'defaults to empty array when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance.fields).to eq []
-    end
-
-    it 'returns blank when initialized with empty array' do
-      instance = klass.new([])
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Label (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'Label (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::Label }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :string' do
-      expect(klass.option_types[:direct]).to include(:label)
-    end
-
-    it 'stores the string as label attribute' do
-      instance = klass.new('My Label')
-      expect(instance.label).to eq 'My Label'
-    end
-
-    it 'defaults to empty string when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance.label).to eq ''
-    end
-
-    it 'uses prepare_config to default to humanized name from parent' do
-      expect(klass).to respond_to(:prepare_config)
-    end
-
-    it 'integration: defaults label to humanized name when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-      YAML
-      # Label uses store_processed_value?, so eo.label is a plain string
-      expect(eo.label).to eq 'Default'
-    end
-
-    it 'integration: preserves explicit label' do
-      eo = config_for(<<~YAML)
-        default:
-          label: Custom Label
-          fields:
-            - test1
-      YAML
-      expect(eo.label).to eq 'Custom Label'
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # CreatableIf, EditableIf, ShowableIf (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'if_condition classes (converted to BaseConfiguration)' do
-    %i[CreatableIf EditableIf ShowableIf].each do |class_name|
-      context "#{class_name}" do
-        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
-        let(:attr_name) { class_name.to_s.underscore.to_sym }
-
-        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-        end
-
-        it 'does not inherit from ConfigBase' do
-          expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-        end
-
-        it 'declares configure_direct with type :hash' do
-          expect(klass.option_types[:direct]).to include(attr_name)
-        end
-
-        it 'stores the hash as the attribute' do
-          instance = klass.new(always: true)
-          expect(instance.send(attr_name)).to eq(always: true)
-        end
-
-        it 'supports hash-like bracket access' do
-          instance = klass.new(always: true)
-          expect(instance[:always]).to eq true
-        end
-
-        it 'defaults to empty hash when initialized with nil' do
-          instance = klass.new(nil)
-          expect(instance.send(attr_name)).to eq({})
-          expect(instance).to be_blank
-        end
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Embed (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'Embed (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::Embed }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:embed)
-    end
-
-    it 'stores resource_name from string input' do
-      instance = klass.new('some_resource')
-      expect(instance.embed[:resource_name]).to eq 'some_resource'
-    end
-
-    it 'stores resource_name from hash input' do
-      instance = klass.new(resource_name: 'some_resource')
-      expect(instance.embed[:resource_name]).to eq 'some_resource'
-    end
-
-    it 'returns blank when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance).to be_blank
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # FieldConfigs (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'FieldConfigs (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldConfigs }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:field_configs)
-    end
-
-    it 'stores the hash as field_configs attribute' do
-      instance = klass.new(test1: { caption_before: 'Test' })
-      expect(instance.field_configs).to eq(test1: { caption_before: 'Test' })
-    end
-
-    it 'defaults to empty hash when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance.field_configs).to eq({})
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # References (converted to BaseConfiguration)
-  # ──────────────────────────────────────────────────────────────
-  describe 'References (converted to BaseConfiguration)' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::References }
-
-    it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-    end
-
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:references)
-    end
-
-    it 'defaults to nil when initialized with nil' do
-      instance = klass.new(nil)
-      expect(instance.references).to be_nil
-    end
-  end
-
-  # Config classes that still use ConfigBase pattern
-  CONFIGBASE_CLASSES = {}.freeze
-
-  # Config classes that use the field-keyed BaseConfiguration pattern
-  FIELD_KEYED_CLASSES = %i[CaptionBefore Labels DialogBefore ShowIf FieldOptions DbConfigs PresetFields].freeze
-
-  # Config classes converted to BaseConfiguration with typed or direct attributes
-  TYPED_CONFIG_CLASSES = %i[
-    BatchTrigger SaveTrigger ViewOptions Filestore ConfigTrigger SaveAction ValidIf SetVariable
-    Fields Label CreatableIf EditableIf ShowableIf Embed FieldConfigs References
-  ].freeze
-
-  # ──────────────────────────────────────────────────────────────
-  # Configuration classes: existence, inheritance, managed_attributes
-  # ──────────────────────────────────────────────────────────────
-  describe 'ConfigBase configuration classes exist with correct structure' do
-    CONFIGBASE_CLASSES.each do |class_name, expected_attributes|
-      context "#{class_name}" do
-        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
-
-        it 'exists under OptionConfigs::ExtraOptionConfigs namespace' do
-          expect(klass).to be_a Class
-        end
-
-        it 'inherits from ConfigBase' do
-          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
-        end
-
-        it "declares managed attributes #{expected_attributes}" do
-          expected_attributes.each do |attr|
-            expect(klass.managed_attributes).to include(attr),
-                                                "Expected #{class_name}.managed_attributes to include :#{attr}"
-          end
-        end
-
-        it 'includes ActiveModel::Validations' do
-          expect(klass.ancestors).to include(ActiveModel::Validations)
-        end
-
-        it 'responds to validators for reflection' do
-          expect(klass).to respond_to(:validators)
-        end
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # CaptionBefore: BaseConfiguration/NamedConfiguration pattern
-  # ──────────────────────────────────────────────────────────────
-  describe 'CaptionBefore uses BaseConfiguration pattern' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::CaptionBefore }
-
-    it 'inherits from BaseConfiguration' do
-      expect(klass.ancestors).to include(OptionConfigs::BaseConfiguration)
-    end
-
-    it 'defines a NamedConfiguration inner class' do
-      expect(klass.const_defined?(:NamedConfiguration)).to be true
-    end
-
-    it 'NamedConfiguration inherits from BaseNamedConfiguration' do
-      expect(klass::NamedConfiguration.ancestors).to include(OptionConfigs::BaseNamedConfiguration)
-    end
-
-    it 'NamedConfiguration declares caption attributes via configure_attributes' do
-      expected = %i[caption edit_caption show_caption new_caption]
-      expected.each do |attr|
-        expect(klass::NamedConfiguration.option_types[:simple]).to include(attr)
-      end
-    end
-
-    context 'initialized with a raw hash' do
-      let(:raw_config) { { test1: 'Simple text', test2: { caption: 'Cap', edit_caption: 'Edit' } } }
-      let(:instance) { klass.new(raw_config) }
-
-      it 'creates named configurations for each field' do
-        expect(instance.configurations).to have_key(:test1)
-        expect(instance.configurations).to have_key(:test2)
-      end
-
-      it 'stores NamedConfiguration objects in configurations' do
-        expect(instance.configurations[:test1]).to be_a klass::NamedConfiguration
-        expect(instance.configurations[:test2]).to be_a klass::NamedConfiguration
-      end
-
-      it 'preprocesses string values into all caption modes' do
-        nc = instance.configurations[:test1]
-        expect(nc.caption).to be_present
-        expect(nc.edit_caption).to eq nc.caption
-        expect(nc.show_caption).to eq nc.caption
-        expect(nc.new_caption).to eq nc.caption
-      end
-
-      it 'preserves hash values with individual mode settings' do
-        nc = instance.configurations[:test2]
-        expect(nc.caption).to include('Cap')
-        expect(nc.edit_caption).to include('Edit')
-      end
-
-      it 'defaults new_caption to edit_caption when not specified' do
-        nc = instance.configurations[:test2]
-        expect(nc.new_caption).to eq nc.edit_caption
-      end
-    end
-
-    context 'hash-like interface' do
-      let(:raw_config) { { test1: 'Caption text' } }
-      let(:instance) { klass.new(raw_config) }
-
-      it '[] returns a NamedConfiguration for a given field' do
-        expect(instance[:test1]).to be_a klass::NamedConfiguration
-      end
-
-      it '[] returns nil for missing fields' do
-        expect(instance[:nonexistent]).to be_nil
-      end
-
-      it 'NamedConfiguration supports [] for attribute access' do
-        nc = instance[:test1]
-        expect(nc[:caption]).to eq nc.caption
-        expect(nc[:edit_caption]).to eq nc.edit_caption
-      end
-
-      it 'supports keys method' do
-        expect(instance.keys).to eq [:test1]
-      end
-
-      it 'supports each iteration' do
-        yielded = []
-        instance.each { |k, v| yielded << [k, v.class] }
-        expect(yielded).to eq [[:test1, klass::NamedConfiguration]]
-      end
-
-      it 'supports blank? for empty config' do
-        empty = klass.new({})
-        expect(empty).to be_blank
-      end
-
-      it 'supports blank? for populated config' do
-        expect(instance).not_to be_blank
-      end
-
-      it 'supports merge! with a plain hash' do
-        instance.merge!(test2: { caption: 'New cap' })
-        expect(instance[:test2]).to be_a klass::NamedConfiguration
-        expect(instance[:test2].caption).to include('New cap')
-      end
-
-      it 'supports []= assignment' do
-        instance[:test3] = { caption: 'Assigned' }
-        expect(instance[:test3]).to be_a klass::NamedConfiguration
-        expect(instance[:test3].caption).to include('Assigned')
-      end
-
-      it 'symbolize_keys returns a plain Hash for backward compat' do
-        result = instance.symbolize_keys
-        expect(result).to be_a Hash
-        expect(result[:test1]).to be_a Hash
-        expect(result[:test1]).to have_key(:caption)
-      end
-    end
-
-    context 'JSON serialization' do
-      let(:raw_config) { { test1: 'Cap text', test2: { caption: 'C', edit_caption: 'E' } } }
-      let(:instance) { klass.new(raw_config) }
-
-      it 'as_json returns a plain nested hash' do
-        json = instance.as_json
-        expect(json).to be_a Hash
-        expect(json['test1']).to be_a Hash
-        expect(json['test1']).to have_key('caption')
-      end
-
-      it 'to_json produces valid JSON matching the expected format' do
-        json_str = instance.to_json
-        parsed = JSON.parse(json_str)
-        expect(parsed).to have_key('test1')
-        expect(parsed['test1']).to have_key('caption')
-      end
-
-      it 'empty config serializes to empty JSON object' do
-        empty = klass.new({})
-        expect(JSON.parse(empty.to_json)).to eq({})
-      end
-    end
-
-    context 'unrecognized NamedConfiguration attributes' do
-      it 'reports a config warning when a field has an unrecognized attribute' do
-        raw = { test1: { caption: 'Valid', bogus_attr: 'Invalid' } }
-        instance = klass.new(raw)
-        expect(instance.config_warnings).to be_present,
-                                            'Expected config_warnings for unrecognized attribute bogus_attr'
-        warning_messages = instance.config_warnings.map { |w| w[:message] }
-        expect(warning_messages.any? { |m| m.include?('bogus_attr') }).to be(true),
-                                                                          "Expected warning mentioning 'bogus_attr', got: #{warning_messages}"
-      end
-
-      it 'does not report warnings for valid attributes only' do
-        raw = { test1: { caption: 'Cap', edit_caption: 'Edit', show_caption: 'Show', new_caption: 'New' } }
-        instance = klass.new(raw)
-        expect(instance.config_warnings).to be_empty,
-                                            "Expected no config_warnings for valid attributes, got: #{instance.config_warnings}"
-      end
-
-      it 'does not report warnings for string values (auto-expanded)' do
-        raw = { test1: 'Simple text' }
-        instance = klass.new(raw)
-        expect(instance.config_warnings).to be_empty,
-                                            "Expected no config_warnings for string value, got: #{instance.config_warnings}"
-      end
-
-      it 'reports multiple unrecognized attributes in a single field' do
-        raw = { test1: { caption: 'Valid', bad1: 'x', bad2: 'y' } }
-        instance = klass.new(raw)
-        warning_messages = instance.config_warnings.map { |w| w[:message] }
-        expect(warning_messages.any? { |m| m.include?('bad1') }).to be(true)
-        expect(warning_messages.any? { |m| m.include?('bad2') }).to be(true)
-      end
-
-      it 'reports unrecognized attributes across multiple fields' do
-        raw = { field1: { caption: 'OK', nope1: 'x' }, field2: { bogus2: 'y' } }
-        instance = klass.new(raw)
-        warning_messages = instance.config_warnings.map { |w| w[:message] }
-        expect(warning_messages.any? { |m| m.include?('nope1') }).to be(true)
-        expect(warning_messages.any? { |m| m.include?('bogus2') }).to be(true)
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Field-keyed classes inheriting ExtraOptionConfigs::BaseConfiguration
-  # ──────────────────────────────────────────────────────────────
-  describe 'Field-keyed BaseConfiguration classes' do
-    FIELD_KEYED_CLASSES.each do |class_name|
-      context "#{class_name}" do
-        let(:klass) { "OptionConfigs::ExtraOptionConfigs::#{class_name}".constantize }
-
-        it 'exists under OptionConfigs::ExtraOptionConfigs namespace' do
-          expect(klass).to be_a Class
-        end
-
-        it 'inherits from ExtraOptionConfigs::BaseConfiguration' do
-          expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
-        end
-
-        it 'supports hash-like interface ([], keys, key?, blank?, merge!, symbolize_keys)' do
-          instance = klass.new({})
-          expect(instance).to respond_to(:[], :keys, :key?, :blank?, :merge!, :symbolize_keys)
-        end
-
-        it 'is blank when initialized with empty hash' do
-          instance = klass.new({})
-          expect(instance).to be_blank
-        end
-
-        it 'supports JSON serialization' do
-          instance = klass.new({})
-          expect(JSON.parse(instance.to_json)).to eq({})
-        end
-
-        it 'provides error collection arrays' do
-          instance = klass.new({})
-          expect(instance.config_errors).to eq([])
-          expect(instance.config_warnings).to eq([])
-        end
-      end
-    end
-
-    context 'Labels stores plain string values' do
-      let(:instance) { OptionConfigs::ExtraOptionConfigs::Labels.new(field1: 'Label One', field2: 'Label Two') }
-
-      it 'returns string values via bracket access' do
-        expect(instance[:field1]).to eq 'Label One'
-        expect(instance[:field2]).to eq 'Label Two'
-      end
-
-      it 'symbolize_keys returns a plain Hash' do
-        expect(instance.symbolize_keys).to eq(field1: 'Label One', field2: 'Label Two')
-      end
-    end
-
-    context 'DialogBefore creates NamedConfiguration for valid entries' do
-      before do
-        create_admin
-        Admin::MessageTemplate.create!(
-          name: 'test_dialog',
-          message_type: :dialog,
-          template_type: :content,
-          template: '<p>test</p>',
-          current_admin: @admin
-        )
-      end
-
-      let(:instance) { OptionConfigs::ExtraOptionConfigs::DialogBefore.new(field1: 'test_dialog') }
-
-      it 'converts string to NamedConfiguration with name attribute' do
-        nc = instance[:field1]
-        expect(nc).to be_a OptionConfigs::BaseNamedConfiguration
-        expect(nc[:name]).to eq 'test_dialog'
-      end
-
-      it 'reports warning for missing template' do
-        instance = OptionConfigs::ExtraOptionConfigs::DialogBefore.new(field1: 'nonexistent')
-        expect(instance.config_warnings).not_to be_empty
-      end
-    end
-
-    context 'ShowIf stores arbitrary condition hashes directly' do
-      let(:instance) { OptionConfigs::ExtraOptionConfigs::ShowIf.new(field1: { other_field: 'value' }) }
-
-      it 'returns condition hashes via bracket access' do
-        expect(instance[:field1]).to eq(other_field: 'value')
-      end
-
-      it 'symbolize_keys returns plain Hash of condition hashes' do
-        expect(instance.symbolize_keys).to eq(field1: { other_field: 'value' })
-      end
-    end
-
-    context 'FieldOptions preprocesses alt_options arrays' do
-      let(:instance) do
-        OptionConfigs::ExtraOptionConfigs::FieldOptions.new(
-          field1: { edit_as: { alt_options: %w[ChoiceA ChoiceB] } }
-        )
-      end
-
-      it 'converts alt_options Array to Hash' do
-        ao = instance[:field1][:edit_as][:alt_options]
-        expect(ao).to be_a Hash
-        expect(ao[:ChoiceA]).to eq 'choicea'
-      end
-    end
-
-    context 'DbConfigs stores column configs directly' do
-      let(:instance) { OptionConfigs::ExtraOptionConfigs::DbConfigs.new(col1: 'type_a') }
-
-      it 'returns values and symbolize_keys produces plain Hash' do
-        expect(instance[:col1]).to eq 'type_a'
-        expect(instance.symbolize_keys).to eq(col1: 'type_a')
-      end
-    end
-
-    context 'PresetFields stores preset values directly' do
-      let(:instance) { OptionConfigs::ExtraOptionConfigs::PresetFields.new(field1: 'default_val') }
-
-      it 'returns values via bracket access' do
-        expect(instance[:field1]).to eq 'default_val'
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ExtraOptions integration: config_instances
-  # ──────────────────────────────────────────────────────────────
-  describe 'ExtraOptions integration' do
-    it 'stores config_instances after initialization (empty since all converted to BaseConfiguration)' do
-      eo = config_for(<<~YAML)
-        default:
-          label: Integration Test
-          fields:
-            - test1
-      YAML
-
-      expect(eo).to respond_to(:config_instances)
-      expect(eo.config_instances).to be_a Hash
-      # All classes are now BaseConfiguration — config_instances should be empty
-      expect(eo.config_instances).to be_empty
-    end
-
-    it 'no ConfigBase classes remain — config_instances is empty' do
-      eo = config_for(<<~YAML)
-        default:
-          label: Full Config
-          fields:
-            - test1
-      YAML
-
-      expect(eo.config_instances).to be_empty
-
-      # Field-keyed classes should NOT be in config_instances
-      FIELD_KEYED_CLASSES.each do |class_name|
-        key = class_name.to_s.underscore.to_sym
-        expect(eo.config_instances).not_to have_key(key),
-                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
-      end
-
-      # Typed/direct config classes should NOT be in config_instances (stored directly as BaseConfiguration attribute)
-      TYPED_CONFIG_CLASSES.each do |class_name|
-        key = EXPECTED_CONFIG_CLASSES.key(class_name)
-        expect(eo.config_instances).not_to have_key(key),
-                                           "#{class_name} should not be in config_instances (stored directly as attribute)"
-      end
-    end
-
-    it 'caption_before is stored directly as a CaptionBefore instance on ExtraOptions' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1: Direct storage test
-      YAML
-
-      expect(eo.caption_before).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
-      expect(eo.caption_before[:test1]).to be_present
-    end
-
-    it 'field-keyed classes are stored directly as BaseConfiguration instances' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          labels:
-            test1: Test Label
-          show_if:
-            test1:
-              other_field: val
-          field_options:
-            test1:
-              no_downcase: true
-          db_configs:
-            test1: some_value
-          preset_fields:
-            test1: preset_val
-      YAML
-
-      expect(eo.labels).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-      expect(eo.show_if).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-      expect(eo.field_options).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-      expect(eo.db_configs).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-      expect(eo.preset_fields).to be_a OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-    end
-
-    it 'BaseConfiguration attribute values are accessible on ExtraOptions' do
-      eo = config_for(<<~YAML)
-        default:
-          label: Matching Test
-          fields:
-            - test1
-            - test2
-          labels:
-            test1: Test One
-          view_options:
-            data_attribute: test1
-          preset_fields:
-            test1: preset_val
-      YAML
-
-      # Label and Fields use store_processed_value?, so stored as plain string/array
-      expect(eo.label).to eq 'Matching Test'
-      expect(eo.fields).to eq %w[test1 test2]
-      # Field-keyed classes are stored directly (not in config_instances)
-      expect(eo.labels[:test1]).to eq 'Test One'
-      # ViewOptions is a BaseConfiguration instance (not store_processed_value?)
-      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
-      expect(eo.view_options[:data_attribute]).to eq 'test1'
-      expect(eo.preset_fields[:test1]).to eq 'preset_val'
-    end
-
-    it 'access_if classes store processed hash values (via store_processed_value?)' do
-      eo = config_for(<<~YAML)
-        default:
-          creatable_if:
-            always: true
-          editable_if:
-            never: true
-          showable_if:
-            user_is_creator: true
-      YAML
-
-      # store_processed_value? means the raw hash is stored, not the BaseConfiguration object
-      expect(eo.creatable_if).to be_a Hash
-      expect(eo.creatable_if[:always]).to eq true
-      expect(eo.editable_if).to be_a Hash
-      expect(eo.editable_if[:never]).to eq true
-      expect(eo.showable_if).to be_a Hash
-      expect(eo.showable_if[:user_is_creator]).to eq true
-    end
-
-    it 'caption_before values match between CaptionBefore instance and ExtraOptions' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1: Simple caption text
-      YAML
-
-      cb = eo.caption_before
-      expect(cb).to be_a OptionConfigs::ExtraOptionConfigs::CaptionBefore
-      expect(cb[:test1][:caption]).to be_present
-    end
-
-    it 'save_trigger is stored directly as a SaveTrigger instance' do
-      eo = config_for(<<~YAML)
-        default:
-          save_trigger:
-            on_save:
-              notify:
-                type: email
-      YAML
-
-      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
-      expect(eo.save_trigger[:on_create]).to be_a Array
-    end
-
-    it 'valid_if is stored directly as a ValidIf BaseConfiguration instance' do
-      eo = config_for(<<~YAML)
-        default:
-          valid_if:
-            on_save:
-              all:
-                this:
-                  test1: is not null
-      YAML
-
-      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
-      expect(eo.valid_if[:on_create]).to be_present
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # config_obj mutation is properly handled outside config classes
-  # ──────────────────────────────────────────────────────────────
-  describe 'config_obj mutation handling' do
-    it 'sets config_obj.db_columns from db_configs after DbConfigs runs' do
-      eo = config_for(<<~YAML)
-        default:
-          db_configs:
-            some_column: some_value
-      YAML
-
-      # db_columns should be set on the config_obj (DynamicModel)
-      expect(@dm.db_columns).to eq(some_column: 'some_value')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ActiveModel::Validations integration (run_validations bridge)
-  # ──────────────────────────────────────────────────────────────
-  # Tests for the run_validations bridge that calls valid? after
-  # setup_named_configurations and bridges ActiveModel::Validations
-  # errors into config_errors via failed_config. Also tests the
-  # TypedAttributeValidator custom validator that checks typed
-  # attributes have the correct type.
-  # ──────────────────────────────────────────────────────────────
-  describe 'ActiveModel::Validations integration' do
-    it 'errors is ActiveModel::Errors, not a plain Array' do
-      instance = OptionConfigs::ExtraOptionConfigs::BaseConfiguration.new({})
-      expect(instance.errors).to be_a(ActiveModel::Errors)
-    end
-
-    it 'validates declarations produce config_errors when value is blank' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
-        configure_direct :test_attr, type: :string
-        validates :test_attr, presence: true
-      end
-
-      instance = test_class.new({})
-      expect(instance.config_errors).not_to be_empty
-      messages = instance.config_errors.map { |e| e[:message] }
-      expect(messages.join(' ')).to match(/test_attr.*blank|can't be blank/i)
-    end
-
-    it 'valid config produces no config_errors from validates' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
-        configure_direct :test_attr, type: :string
-        validates :test_attr, presence: true
-
-        def setup_named_configurations
-          self.test_attr = 'a valid value'
-        end
-      end
-
-      instance = test_class.new({})
-      expect(instance.config_errors).to be_empty
-    end
-
-    it 'TypedAttributeValidator catches wrong type' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
-        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
-        validates :my_typed, 'validates/typed_attribute': true
-
-        def setup_named_configurations
-          setup_all_options_typed(hash_configuration)
-        end
-      end
-
-      instance = test_class.new({})
-      # Manually assign wrong type after initialization
-      instance.my_typed = 'wrong'
-      instance.valid?
-      expect(instance.errors[:my_typed]).not_to be_empty
-      expect(instance.errors[:my_typed].join(' ')).to match(/must be a.*TriggerTasks.*got String/)
-    end
-
-    it 'TypedAttributeValidator passes correct type' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
-        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
-        validates :my_typed, 'validates/typed_attribute': true
-
-        def setup_named_configurations
-          setup_all_options_typed(hash_configuration)
-        end
-      end
-
-      instance = test_class.new(my_typed: { notify: { type: 'email' } })
-      expect(instance.my_typed).to be_a(OptionConfigs::ExtraOptionConfigs::TriggerTasks)
-      expect(instance.valid?).to be true
-      expect(instance.errors[:my_typed]).to be_empty
-    end
-
-    it 'TypedAttributeValidator allows nil' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BaseConfiguration) do
-        configure_typed_attribute :my_typed, type: OptionConfigs::ExtraOptionConfigs::TriggerTasks
-        validates :my_typed, 'validates/typed_attribute': true
-
-        def setup_named_configurations
-          # Don't set my_typed — leave it nil
-        end
-      end
-
-      instance = test_class.new({})
-      expect(instance.my_typed).to be_nil
-      expect(instance.valid?).to be true
-      expect(instance.errors[:my_typed]).to be_empty
-    end
-
-    it 'full integration: BatchTrigger subclass with validates produces config_errors on empty config' do
-      test_class = Class.new(OptionConfigs::ExtraOptionConfigs::BatchTrigger) do
-        validates :on_record, presence: true
-      end
-
-      instance = test_class.new({})
-      expect(instance.config_errors).not_to be_empty
-      messages = instance.config_errors.map { |e| e[:message] }
-      expect(messages.join(' ')).to match(/on_record.*blank|can't be blank/i)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # validate callbacks (migrated from manual failed_config calls)
-  # ──────────────────────────────────────────────────────────────
-  # Phase 3 of issue #986: Verify that validation logic in ValidIf,
-  # SaveTrigger, and SetVariable subclasses produces the expected
-  # config_errors and ActiveModel::Errors when given invalid input.
-  # Tests 1-7 verify config_errors (pass now, pass after migration).
-  # Tests 8-10 verify ActiveModel errors (FAIL now, pass after migration).
-  describe 'validate callbacks' do
-    describe 'ValidIf' do
-      it 'with invalid keys has errors on :valid_if' do
-        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_invalid_key: { always: true })
-        expect(instance.config_errors).not_to be_empty
-        err = instance.config_errors.find { |e| e[:type] == :valid_if }
-        expect(err).to be_present
-        expect(err[:message]).to match(/invalid keys/)
-      end
-
-      it 'with valid keys has no validation errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_save: { all: { this: { field: 'is not null' } } })
-        expect(instance.config_errors).to be_empty
-      end
-
-      it 'with invalid keys has ActiveModel errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::ValidIf.new(on_invalid_key: { always: true })
-        expect(instance.errors[:valid_if]).not_to be_empty
-      end
-    end
-
-    describe 'SaveTrigger' do
-      it 'with invalid keys has errors on :save_trigger' do
-        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_invalid_trigger: { something: true })
-        expect(instance.config_errors).not_to be_empty
-        err = instance.config_errors.find { |e| e[:type] == :save_trigger }
-        expect(err).to be_present
-        expect(err[:message]).to match(/invalid keys/)
-      end
-
-      it 'with valid keys has no validation errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_create: [{ notify: { type: 'email' } }])
-        expect(instance.config_errors).to be_empty
-      end
-
-      it 'with invalid keys has ActiveModel errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::SaveTrigger.new(on_invalid_trigger: { something: true })
-        expect(instance.errors[:save_trigger]).not_to be_empty
-      end
-    end
-
-    describe 'SetVariable' do
-      it 'with non-array input has errors on :set_variables' do
-        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new({ name: 'var1', value: 'val1' })
-        expect(instance.config_errors).not_to be_empty
-        err = instance.config_errors.find { |e| e[:type] == :set_variables }
-        expect(err).to be_present
-        expect(err[:message]).to match(/must be an array/)
-      end
-
-      it 'with invalid entries has errors on :set_variables' do
-        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new([{ bad_key: 'test' }])
-        expect(instance.config_errors).not_to be_empty
-        err = instance.config_errors.find { |e| e[:type] == :set_variables }
-        expect(err).to be_present
-        expect(err[:message]).to match(/must have 'name' and 'value' keys/)
-      end
-
-      it 'with valid entries has no validation errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new([{ name: 'v', value: 'x' }])
-        expect(instance.config_errors).to be_empty
-      end
-
-      it 'with non-array has ActiveModel errors' do
-        instance = OptionConfigs::ExtraOptionConfigs::SetVariable.new({ name: 'var1', value: 'val1' })
-        expect(instance.errors[:set_variables]).not_to be_empty
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # References.reprocess (#986)
-  # Verify that References.reprocess can re-run prepare_config on an
-  # already-initialized ExtraOptions instance after its references
-  # attribute has been mutated. This method does not exist yet and
-  # these tests are expected to FAIL in the red phase.
-  # ──────────────────────────────────────────────────────────────
-  describe 'References.reprocess' do
-    let(:references_class) { OptionConfigs::ExtraOptionConfigs::References }
-
-    it 'exists as a class method on References' do
-      expect(references_class).to respond_to(:reprocess)
-    end
-
-    it 're-processes references after post-initialization mutation' do
-      yaml = <<~YAML
-        default:
-          label: Test
-          references:
-            player_contact:
-              from: this
-              add: many
-      YAML
-      eo = config_for(yaml)
-
-      # Initial references should have been processed (singular key, metadata populated)
-      expect(eo.references).to be_a(Hash)
-      initial_ref = eo.references[:player_contact]
-      expect(initial_ref).to be_present
-      expect(initial_ref[:player_contact][:to_record_label]).to be_present
-
-      # Mutate references with a raw hash using plural keys (simulating post-init mutation)
-      eo.references = { player_contacts: { from: 'this', add: 'many' } }
-
-      # Call reprocess to re-run prepare_config on the mutated value
-      references_class.reprocess(eo)
-
-      # After reprocessing, plural keys should be singularized
-      expect(eo.references).to be_a(Hash)
-      reprocessed_ref = eo.references[:player_contact]
-      expect(reprocessed_ref).to be_present, 'Expected plural key :player_contacts to be singularized to :player_contact'
-      expect(reprocessed_ref[:player_contact][:to_record_label]).to be_present
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Old clean_ methods removed (#986)
-  # Confirm that the 21 legacy clean_ methods have been removed from
-  # ExtraOptions. They were replaced by config_class_registry classes.
-  # ──────────────────────────────────────────────────────────────
-  describe 'old clean_ methods removed' do
-    let(:removed_clean_methods) do
-      %i[
-        clean_label_def
-        clean_caption_before_def
-        clean_dialog_before_def
-        clean_labels_def
-        clean_show_if_def
-        clean_save_action_def
-        clean_view_options_def
-        clean_db_configs_def
-        clean_fields_def
-        clean_field_options_def
-        clean_filestore_def
-        clean_access_if_def
-        clean_valid_if_def
-        clean_embed_def
-        clean_references_def
-        clean_save_triggers
-        clean_batch_triggers
-        clean_config_triggers
-        clean_preset_fields
-        clean_set_variables_def
-        clean_field_configs
-      ]
-    end
-
-    it 'no longer defines any clean_ instance methods' do
-      removed_clean_methods.each do |method_name|
-        expect(OptionConfigs::ExtraOptions.method_defined?(method_name, false))
-          .to be(false), "Expected #{method_name} to be removed from ExtraOptions"
-      end
-    end
-
-    it 'still initializes correctly without clean_ methods' do
-      yaml = <<~YAML
-        default:
-          label: Test
-          fields:
-            - test_field
-          caption_before:
-            test_field: A Caption
-          show_if:
-            test_field:
-              test_field2: value
-          view_options:
-            show_result_options: true
-      YAML
-      eo = config_for(yaml)
-      expect(eo.label).to eq('Test')
-      expect(eo.caption_before).to be_present
-      expect(eo.show_if).to be_present
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Validate callbacks for remaining classes (#986)
-  #
-  # RED PHASE: These tests verify that DialogBefore, Embed,
-  # References, and FieldConfigs use ActiveModel validate callbacks
-  # (errors.add) instead of calling failed_config directly.
-  #
-  # Currently these classes report errors via failed_config in
-  # prepare_config or add_named_configuration. After migration,
-  # they should populate ActiveModel errors on the INSTANCE,
-  # which run_validations bridges into config_errors.
-  #
-  # These tests WILL FAIL until the production code is migrated.
-  # ──────────────────────────────────────────────────────────────
-  describe 'validate callbacks for remaining classes (#986)' do
-    describe 'DialogBefore' do
-      let(:klass) { OptionConfigs::ExtraOptionConfigs::DialogBefore }
-
-      it 'produces ActiveModel errors when value is an invalid type' do
-        # 12345 is neither String nor Hash — should be rejected
-        instance = klass.new(test_field: 12_345)
-        expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
-                                                                              'Expected ActiveModel error on :dialog_before for invalid type, but none found'
-      end
-
-      it 'produces ActiveModel errors (warning level) when template does not exist' do
-        instance = klass.new(test_field: { name: 'nonexistent_template_xyz_999' })
-        # After migration, missing template should produce an ActiveModel error on :dialog_before
-        expect(instance.errors.any? { |e| e.attribute == :dialog_before }).to be(true),
-                                                                              'Expected ActiveModel error on :dialog_before for missing template, but none found'
-      end
-
-      it 'has no ActiveModel errors when given valid configuration' do
-        # Create a real message template so the validation passes
-        Admin::MessageTemplate.create!(
-          name: 'test_dialog_template_986',
-          message_type: :dialog,
-          template_type: :content,
-          template: '<p>Test</p>',
-          current_admin: @admin
-        )
-        instance = klass.new(test_field: { name: 'test_dialog_template_986' })
-        expect(instance.errors).to be_empty,
-                                   "Expected no ActiveModel errors for valid dialog_before, got: #{instance.errors.full_messages}"
-      end
-    end
-
-    describe 'Embed' do
-      let(:klass) { OptionConfigs::ExtraOptionConfigs::Embed }
-
-      it 'produces ActiveModel errors on the instance when resource does not exist' do
-        # Simulate what the registry does: call prepare_config then create instance
-        yaml = <<~YAML
-          default:
-            label: Test
-            embed: nonexistent_resource_xyz_999
-        YAML
-        eo = config_for(yaml)
-
-        # Re-create the instance directly to check ActiveModel errors on INSTANCE
-        processed = klass.prepare_config('nonexistent_resource_xyz_999', eo)
-        instance = klass.new(processed)
-        expect(instance.errors.any? { |e| e.attribute == :embed }).to be(true),
-                                                                      'Expected ActiveModel error on :embed for non-existent resource, but none found on instance'
-      end
-
-      it 'has no ActiveModel errors on the instance when embed is valid' do
-        # Use proper plural resource name that Resources::Models recognizes
-        yaml = <<~YAML
-          default:
-            label: Test
-            embed: player_contacts
-        YAML
-        eo = config_for(yaml)
-
-        processed = klass.prepare_config('player_contacts', eo)
-        instance = klass.new(processed)
-        expect(instance.errors).to be_empty,
-                                   "Expected no ActiveModel errors for valid embed, got: #{instance.errors.full_messages}"
-      end
-    end
-
-    describe 'References' do
-      let(:klass) { OptionConfigs::ExtraOptionConfigs::References }
-
-      it 'produces ActiveModel errors on the instance when reference class does not exist' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            references:
-              nonexistent_model_xyz_999:
-                from: this
-                add: many
-        YAML
-        eo = config_for(yaml)
-
-        raw = { nonexistent_model_xyz_999: { from: 'this', add: 'many' } }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors.any? { |e| e.attribute == :references }).to be(true),
-                                                                           'Expected ActiveModel error on :references for non-existent class, but none found on instance'
-      end
-
-      it 'has no ActiveModel errors on the instance when references are valid' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            references:
-              player_contact:
-                from: this
-                add: many
-        YAML
-        eo = config_for(yaml)
-
-        raw = { player_contact: { from: 'this', add: 'many' } }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors).to be_empty,
-                                   "Expected no ActiveModel errors for valid references, got: #{instance.errors.full_messages}"
-      end
-    end
-
-    describe 'FieldConfigs' do
-      let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldConfigs }
-
-      it 'produces ActiveModel errors when a field value is not a Hash' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            fields:
-              - test_field
-            field_configs:
-              test_field: not_a_hash
-        YAML
-        eo = config_for(yaml)
-
-        raw = { test_field: 'not_a_hash' }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
-                                                                              'Expected ActiveModel error on :field_configs for non-Hash field value, but none found on instance'
-      end
-
-      it 'produces ActiveModel errors when fields are not in the field list' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            fields:
-              - test_field
-            field_configs:
-              unknown_field:
-                caption_before: Test Caption
-        YAML
-        eo = config_for(yaml)
-
-        raw = { unknown_field: { caption_before: 'Test Caption' } }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
-                                                                              'Expected ActiveModel error on :field_configs for field not in field list, but none found on instance'
-      end
-
-      it 'produces ActiveModel errors when field_configs contain invalid keys' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            fields:
-              - test_field
-            field_configs:
-              test_field:
-                totally_invalid_key: some_value
-        YAML
-        eo = config_for(yaml)
-
-        raw = { test_field: { totally_invalid_key: 'some_value' } }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors.any? { |e| e.attribute == :field_configs }).to be(true),
-                                                                              'Expected ActiveModel error on :field_configs for invalid keys, but none found on instance'
-      end
-
-      it 'has no ActiveModel errors when field_configs are valid' do
-        yaml = <<~YAML
-          default:
-            label: Test
-            fields:
-              - test_field
-            field_configs:
-              test_field:
-                caption_before: A Caption
-        YAML
-        eo = config_for(yaml)
-
-        raw = { test_field: { caption_before: 'A Caption' } }
-        processed = klass.prepare_config(raw, eo)
-        instance = klass.new(processed)
-        expect(instance.errors).to be_empty,
-                                   "Expected no ActiveModel errors for valid field_configs, got: #{instance.errors.full_messages}"
-      end
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # NfsStoreConfig (issue #986 – migrated from ActivityLogOptions#clean_nfs_store_def)
-  # Validates nfs_store keys and delegates pipeline cleaning to NfsStore::Config::ExtraOptions.clean_def
-  # ──────────────────────────────────────────────────────────────
-  describe 'NfsStoreConfig' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::NfsStoreConfig }
-
-    it 'exists and inherits from BaseConfiguration' do
-      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-    end
-
-    it 'stores processed value' do
-      expect(klass.store_processed_value?).to be true
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:nfs_store)
-    end
-
-    it 'produces ActiveModel errors for invalid top-level nfs_store keys' do
-      raw = { always_use_this_for_access_control: true, invalid_key_xyz: 'bad' }
-      instance = klass.new(raw)
-      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
-                                                                        'Expected ActiveModel error on :nfs_store for invalid top-level keys'
-    end
-
-    it 'produces ActiveModel errors for invalid can sub-keys' do
-      raw = { can: { download_if: true, bogus_permission: 'bad' } }
-      instance = klass.new(raw)
-      expect(instance.errors.any? { |e| e.attribute == :nfs_store }).to be(true),
-                                                                        'Expected ActiveModel error on :nfs_store for invalid can sub-keys'
-    end
-
-    it 'has no ActiveModel errors when all keys are valid' do
-      raw = { always_use_this_for_access_control: true, can: { download_if: true } }
-      instance = klass.new(raw)
-      expect(instance.errors).to be_empty,
-                                 "Expected no ActiveModel errors for valid nfs_store keys, got: #{instance.errors.full_messages}"
-    end
-
-    it 'has no ActiveModel errors when nfs_store is nil' do
-      instance = klass.new(nil)
-      expect(instance.errors).to be_empty,
-                                 "Expected no ActiveModel errors for nil nfs_store, got: #{instance.errors.full_messages}"
-    end
-
-    it 'delegates pipeline cleaning via prepare_config' do
-      raw = { pipeline: [], user_file_actions: [] }
-      expect(NfsStore::Config::ExtraOptions).to receive(:clean_def).with(raw)
-      klass.prepare_config(raw, nil)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ESignConfig (issue #986 – migrated from ActivityLogOptions#clean_e_sign_def)
-  # Transforms e_sign document_reference structure: wraps in {item: ...},
-  # singularizes keys, and resolves model references.
-  # ──────────────────────────────────────────────────────────────
-  describe 'ESignConfig' do
-    let(:klass) { OptionConfigs::ExtraOptionConfigs::ESignConfig }
-
-    it 'exists and inherits from BaseConfiguration' do
-      expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
-    end
-
-    it 'stores processed value' do
-      expect(klass.store_processed_value?).to be true
-    end
-
-    it 'declares configure_direct with type :hash' do
-      expect(klass.option_types[:direct]).to include(:e_sign)
-    end
-
-    it 'wraps document_reference in {item: ...} if not already wrapped' do
-      raw = { document_reference: { player_contacts: { label: 'Contact' } } }
-      result = klass.prepare_config(raw, nil)
-      expect(result[:document_reference]).to have_key(:item),
-                                             'Expected document_reference to be wrapped in {item: ...}'
-    end
-
-    it 'does not double-wrap document_reference that already has :item key' do
-      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
-      result = klass.prepare_config(raw, nil)
-      expect(result[:document_reference][:item]).not_to have_key(:item),
-                                                        'Expected document_reference not to be double-wrapped'
-    end
-
-    it 'singularizes keys within each reference item' do
-      raw = { document_reference: { item: { player_contacts: { label: 'Contact' } } } }
-      result = klass.prepare_config(raw, nil)
-      item = result[:document_reference][:item]
-      expect(item).to have_key(:player_contact),
-                      'Expected pluralized key :player_contacts to be singularized to :player_contact'
-      expect(item).not_to have_key(:player_contacts),
-                          'Expected original pluralized key :player_contacts to be removed after singularization'
-    end
-
-    it 'resolves model references with to_record_label, no_master_association, to_model_name_us' do
-      raw = { document_reference: { item: { player_contacts: { label: 'My Label' } } } }
-      result = klass.prepare_config(raw, nil)
-      ref = result[:document_reference][:item][:player_contact]
-      expect(ref).to have_key(:to_record_label),
-                     'Expected :to_record_label to be set on resolved reference'
-      expect(ref).to have_key(:to_model_name_us),
-                     'Expected :to_model_name_us to be set on resolved reference'
-    end
-
-    it 'returns nil from prepare_config when raw is nil' do
-      result = klass.prepare_config(nil, nil)
-      expect(result).to be_nil
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # ActivityLogOptions config_class_registry integration (issue #986)
-  # After migration, nfs_store and e_sign should be registered config classes
-  # and the old clean_ instance methods should no longer exist.
-  # ──────────────────────────────────────────────────────────────
-  describe 'ActivityLogOptions config_class_registry' do
-    it 'extends parent registry with nfs_store' do
-      registry = OptionConfigs::ActivityLogOptions.config_class_registry
-      expect(registry).to have_key(:nfs_store),
-                          'Expected ActivityLogOptions.config_class_registry to include :nfs_store'
-    end
-
-    it 'extends parent registry with e_sign' do
-      registry = OptionConfigs::ActivityLogOptions.config_class_registry
-      expect(registry).to have_key(:e_sign),
-                          'Expected ActivityLogOptions.config_class_registry to include :e_sign'
-    end
-
-    it 'maps nfs_store to NfsStoreConfig class' do
-      registry = OptionConfigs::ActivityLogOptions.config_class_registry
-      expect(registry[:nfs_store]).to eq(OptionConfigs::ExtraOptionConfigs::NfsStoreConfig)
-    end
-
-    it 'maps e_sign to ESignConfig class' do
-      registry = OptionConfigs::ActivityLogOptions.config_class_registry
-      expect(registry[:e_sign]).to eq(OptionConfigs::ExtraOptionConfigs::ESignConfig)
-    end
-
-    it 'returns empty add_key_attributes' do
-      expect(OptionConfigs::ActivityLogOptions.add_key_attributes).to eq([])
-    end
-
-    it 'does not define clean_nfs_store_def as instance method' do
-      expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_nfs_store_def, false)).to be false
-    end
-
-    it 'does not define clean_e_sign_def as instance method' do
-      expect(OptionConfigs::ActivityLogOptions.method_defined?(:clean_e_sign_def, false)).to be false
-    end
-  end
-end
diff --git a/spec/models/option_configs/extra_options_clean_methods_spec.rb b/spec/models/option_configs/extra_options_clean_methods_spec.rb
deleted file mode 100644
index 786a0d9daf..0000000000
--- a/spec/models/option_configs/extra_options_clean_methods_spec.rb
+++ /dev/null
@@ -1,1196 +0,0 @@
-# frozen_string_literal: true
-
-require 'rails_helper'
-require './db/table_generators/dynamic_models_table'
-
-# Phase 1 of issue #986: Capture the current behavior of each ExtraOptions `clean_...` method
-# with explicit tests. These tests document the exact output format produced by each method
-# given known inputs, establishing a safety net for the Phase 2 refactoring into
-# dedicated configuration classes.
-#
-# Each describe block covers one `clean_...` method. Tests verify:
-# - Default initialization when no config is provided
-# - Correct transformation of valid input
-# - Edge cases: nil inputs, empty hashes, invalid keys, nested structures
-#
-# The test strategy instantiates ExtraOptions through the standard parse path
-# (DynamicModel#option_configs) so that the full initialization sequence runs,
-# including inter-method dependencies.
-RSpec.describe 'ExtraOptions clean methods', type: :model do
-  include MasterSupport
-  include ModelSupport
-  include DynamicModelSupport
-
-  before(:each) do
-    create_admin
-    create_user
-    setup_access :trackers
-    setup_access :tracker_histories
-    @dm = generate_test_dynamic_model
-    setup_access :dynamic_model__test_created_by_recs, user: @user
-  end
-
-  # Helper: update the DynamicModel with given YAML options and return the first option config
-  def config_for(yaml)
-    @dm.update!(options: yaml, current_admin: @admin)
-    @dm.option_configs.first
-  end
-
-  # Helper: return all option configs for the given YAML
-  def all_configs_for(yaml)
-    @dm.update!(options: yaml, current_admin: @admin)
-    @dm.option_configs
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_fields_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_fields_def' do
-    it 'defaults fields to an empty array when not specified in options' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No fields
-      YAML
-      # When no fields are specified in options, fields defaults to []
-      # (the DynamicModel may have its own field_list but clean_fields_def
-      # only sets [] if fields is nil in the options config)
-      expect(eo.fields).to be_an Array
-    end
-
-    it 'preserves a provided field list' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-      YAML
-      expect(eo.fields).to eq %w[test1 test2]
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_label_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_label_def' do
-    it 'defaults label to a humanized version of the config name' do
-      eo = config_for(<<~YAML)
-        my_custom_name:
-          fields:
-            - test1
-      YAML
-      expect(eo.label).to eq 'My custom name'
-    end
-
-    it 'preserves an explicitly set label' do
-      eo = config_for(<<~YAML)
-        default:
-          label: Custom Label
-      YAML
-      expect(eo.label).to eq 'Custom Label'
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_caption_before_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_caption_before_def' do
-    it 'defaults caption_before to a blank CaptionBefore when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No captions
-      YAML
-      expect(eo.caption_before).to be_blank
-    end
-
-    it 'converts a plain string caption to a hash with all caption modes' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1: Simple caption text
-      YAML
-
-      cb = eo.caption_before[:test1]
-      expect(cb).to respond_to(:[])
-      expect(cb[:caption]).to be_present
-      expect(cb[:edit_caption]).to be_present
-      expect(cb[:show_caption]).to be_present
-      expect(cb[:new_caption]).to be_present
-      # All modes should have the same HTML-converted value
-      expect(cb[:caption]).to eq cb[:edit_caption]
-      expect(cb[:caption]).to eq cb[:show_caption]
-      expect(cb[:caption]).to eq cb[:new_caption]
-    end
-
-    it 'converts text to HTML via Formatter::Substitution.text_to_html' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1: "Line one\\nLine two"
-      YAML
-
-      cb = eo.caption_before[:test1]
-      # The text_to_html conversion should produce HTML content
-      expect(cb[:caption]).to be_a String
-      expect(cb[:caption]).not_to be_empty
-    end
-
-    it 'preserves hash-style caption_before with individual mode values' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1:
-              caption: Show and edit caption
-              edit_caption: Edit only caption
-              show_caption: Show only caption
-      YAML
-
-      cb = eo.caption_before[:test1]
-      expect(cb[:caption]).to include('Show and edit caption')
-      expect(cb[:edit_caption]).to include('Edit only caption')
-      expect(cb[:show_caption]).to include('Show only caption')
-    end
-
-    it 'defaults new_caption to edit_caption when not explicitly set' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1:
-              edit_caption: Edit caption value
-      YAML
-
-      cb = eo.caption_before[:test1]
-      expect(cb[:new_caption]).to eq cb[:edit_caption]
-    end
-
-    it 'symbolizes caption_before keys' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          caption_before:
-            test1: A caption
-      YAML
-
-      expect(eo.caption_before.keys.first).to be_a Symbol
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_dialog_before_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_dialog_before_def' do
-    it 'defaults dialog_before to a blank DialogBefore when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No dialogs
-      YAML
-      expect(eo.dialog_before).to be_blank
-    end
-
-    it 'converts a string value to a hash with name key' do
-      # Create a message template first, so the warning is not generated
-      Admin::MessageTemplate.create!(
-        name: 'test_dialog_template',
-        message_type: :dialog,
-        template_type: :content,
-        template: '<p>test</p>',
-        current_admin: @admin
-      )
-
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          dialog_before:
-            test1: test_dialog_template
-      YAML
-
-      db = eo.dialog_before[:test1]
-      expect(db).to respond_to(:[]) # NamedConfiguration with bracket access
-      expect(db[:name]).to eq 'test_dialog_template'
-    end
-
-    it 'preserves a hash value with name key' do
-      Admin::MessageTemplate.create!(
-        name: 'test_dialog_hash',
-        message_type: :dialog,
-        template_type: :content,
-        template: '<p>test</p>',
-        current_admin: @admin
-      )
-
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          dialog_before:
-            test1:
-              name: test_dialog_hash
-      YAML
-
-      db = eo.dialog_before[:test1]
-      expect(db[:name]).to eq 'test_dialog_hash'
-    end
-
-    it 'reports a warning when the named message template does not exist' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          dialog_before:
-            test1: nonexistent_template
-      YAML
-
-      expect(eo.config_warnings).not_to be_empty
-      warn_msg = eo.config_warnings.find { |w| w[:type] == :dialog_before }
-      expect(warn_msg).to be_present
-    end
-
-    it 'reports an error when the value is not a String or Hash' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          dialog_before:
-            test1:
-              - invalid_array_item
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :dialog_before }
-      expect(err).to be_present
-    end
-
-    it 'symbolizes dialog_before keys' do
-      Admin::MessageTemplate.create!(
-        name: 'dialog_sym_test',
-        message_type: :dialog,
-        template_type: :content,
-        template: '<p>test</p>',
-        current_admin: @admin
-      )
-
-      eo = config_for(<<~YAML)
-        default:
-          dialog_before:
-            test1: dialog_sym_test
-      YAML
-
-      expect(eo.dialog_before.keys.first).to be_a Symbol
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_labels_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_labels_def' do
-    it 'defaults labels to a blank Labels instance when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No labels
-      YAML
-      expect(eo.labels).to be_blank
-    end
-
-    it 'preserves explicitly set labels and symbolizes keys' do
-      eo = config_for(<<~YAML)
-        default:
-          labels:
-            test1: Test One
-            test2: Test Two
-      YAML
-
-      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_show_if_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_show_if_def' do
-    it 'defaults show_if to a blank ShowIf instance when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No show_if
-      YAML
-      expect(eo.show_if).to be_blank
-    end
-
-    it 'preserves explicitly set show_if conditions and symbolizes keys' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-          show_if:
-            test2:
-              test1: some_value
-      YAML
-
-      expect(eo.show_if).to have_key(:test2)
-      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
-    end
-
-    it 'does not overwrite existing show_if when show_if_condition_strings provides a duplicate' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-          show_if:
-            test2:
-              test1: existing_value
-          show_if_condition_strings:
-            test2: "[test1] = 'other_value'"
-      YAML
-
-      # The existing show_if should take priority
-      expect(eo.show_if[:test2]).to eq(test1: 'existing_value')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_save_action_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_save_action_def' do
-    it 'defaults save_action to a blank SaveAction when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No save action
-      YAML
-      expect(eo.save_action).to be_a OptionConfigs::ExtraOptionConfigs::SaveAction
-      expect(eo.save_action).to be_blank
-    end
-
-    it 'cascades on_save to on_create and on_update as defaults' do
-      eo = config_for(<<~YAML)
-        default:
-          save_action:
-            on_save:
-              label: Saved
-      YAML
-
-      expect(eo.save_action.save_action[:on_save]).to eq(label: 'Saved')
-      expect(eo.save_action.save_action[:on_create]).to eq(label: 'Saved')
-      expect(eo.save_action.save_action[:on_update]).to eq(label: 'Saved')
-    end
-
-    it 'merges on_save into existing on_create and on_update without overwriting them' do
-      eo = config_for(<<~YAML)
-        default:
-          save_action:
-            on_save:
-              label: Default
-              notify: true
-            on_create:
-              label: Created
-            on_update:
-              another_key: updated_val
-      YAML
-
-      expect(eo.save_action.save_action[:on_create][:label]).to eq 'Created'
-      expect(eo.save_action.save_action[:on_create][:notify]).to eq true
-      expect(eo.save_action.save_action[:on_update][:label]).to eq 'Default'
-      expect(eo.save_action.save_action[:on_update][:another_key]).to eq 'updated_val'
-    end
-
-    it 'symbolizes save_action keys' do
-      eo = config_for(<<~YAML)
-        default:
-          save_action:
-            on_save:
-              label: Test
-      YAML
-      expect(eo.save_action.save_action.keys).to all(be_a Symbol)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_view_options_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_view_options_def' do
-    it 'defaults view_options to a blank ViewOptions when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No view options
-      YAML
-      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
-      expect(eo.view_options).to be_blank
-    end
-
-    it 'preserves view_options and symbolizes keys' do
-      eo = config_for(<<~YAML)
-        default:
-          view_options:
-            data_attribute: field_1
-            show_embedded: true
-      YAML
-      expect(eo.view_options).to be_a OptionConfigs::ExtraOptionConfigs::ViewOptions
-      expect(eo.view_options.view_options).to eq(data_attribute: 'field_1', show_embedded: true)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_db_configs_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_db_configs_def' do
-    it 'defaults db_configs to a blank DbConfigs instance when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No db configs
-      YAML
-      expect(eo.db_configs).to be_blank
-    end
-
-    it 'symbolizes db_configs keys' do
-      eo = config_for(<<~YAML)
-        default:
-          db_configs:
-            some_column: some_value
-      YAML
-      expect(eo.db_configs.keys).to all(be_a Symbol)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_access_if_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_access_if_def' do
-    it 'defaults all access_if attributes to empty hashes' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No access
-      YAML
-
-      expect(eo.creatable_if).to eq({})
-      expect(eo.editable_if).to eq({})
-      expect(eo.showable_if).to eq({})
-    end
-
-    it 'preserves and symbolizes creatable_if, editable_if, showable_if' do
-      eo = config_for(<<~YAML)
-        default:
-          creatable_if:
-            always: true
-          editable_if:
-            never: true
-          showable_if:
-            user_is_creator: true
-      YAML
-
-      expect(eo.creatable_if).to eq(always: true)
-      expect(eo.editable_if).to eq(never: true)
-      expect(eo.showable_if).to eq(user_is_creator: true)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_valid_if_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_valid_if_def' do
-    it 'defaults valid_if to a blank ValidIf when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No valid_if
-      YAML
-      expect(eo.valid_if).to be_a OptionConfigs::ExtraOptionConfigs::ValidIf
-      expect(eo.valid_if).to be_blank
-    end
-
-    it 'cascades on_save to on_create and on_update as defaults' do
-      eo = config_for(<<~YAML)
-        default:
-          valid_if:
-            on_save:
-              all:
-                this:
-                  test1: is not null
-      YAML
-
-      expect(eo.valid_if.valid_if[:on_save]).to be_present
-      expect(eo.valid_if.valid_if[:on_create]).to eq eo.valid_if.valid_if[:on_save]
-      expect(eo.valid_if.valid_if[:on_update]).to eq eo.valid_if.valid_if[:on_save]
-    end
-
-    it 'merges on_save into existing on_create and on_update' do
-      eo = config_for(<<~YAML)
-        default:
-          valid_if:
-            on_save:
-              all:
-                this:
-                  test1: is not null
-            on_create:
-              all:
-                this:
-                  test2: is not null
-      YAML
-
-      expect(eo.valid_if.valid_if[:on_create]).to have_key(:all)
-    end
-
-    it 'reports an error for invalid trigger keys' do
-      eo = config_for(<<~YAML)
-        default:
-          valid_if:
-            on_invalid_key:
-              always: true
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :valid_if }
-      expect(err).to be_present
-    end
-
-    it 'symbolizes valid_if keys' do
-      eo = config_for(<<~YAML)
-        default:
-          valid_if:
-            on_save:
-              always: true
-      YAML
-      expect(eo.valid_if.valid_if.keys).to all(be_a Symbol)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_filestore_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_filestore_def' do
-    it 'defaults filestore to a blank Filestore when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No filestore
-      YAML
-      expect(eo.filestore).to be_a OptionConfigs::ExtraOptionConfigs::Filestore
-      expect(eo.filestore).to be_blank
-    end
-
-    it 'preserves and symbolizes filestore keys' do
-      eo = config_for(<<~YAML)
-        default:
-          filestore:
-            always_use_this_for_access_control: true
-      YAML
-      expect(eo.filestore.symbolize_keys).to eq(always_use_this_for_access_control: true)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_field_options_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_field_options_def' do
-    it 'defaults field_options to a blank FieldOptions instance when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No field options
-      YAML
-      expect(eo.field_options).to be_blank
-    end
-
-    it 'preserves field_options and symbolizes keys' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_options:
-            test1:
-              no_downcase: true
-      YAML
-      expect(eo.field_options[:test1]).to eq(no_downcase: true)
-    end
-
-    it 'converts edit_as.alt_options from Array to Hash' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_options:
-            test1:
-              edit_as:
-                field_type: select
-                alt_options:
-                  - Choice A
-                  - Choice B
-      YAML
-
-      ao = eo.field_options[:test1][:edit_as][:alt_options]
-      expect(ao).to be_a Hash
-      # Array items are converted: key is symbolized, value is downcased string
-      expect(ao[:'Choice A']).to eq 'choice a'
-      expect(ao[:'Choice B']).to eq 'choice b'
-    end
-
-    it 'preserves edit_as.alt_options when already a Hash' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_options:
-            test1:
-              edit_as:
-                field_type: select
-                alt_options:
-                  'Option 1': opt1
-                  'Option 2': opt2
-      YAML
-
-      ao = eo.field_options[:test1][:edit_as][:alt_options]
-      expect(ao).to be_a Hash
-      expect(ao[:'Option 1']).to eq 'opt1'
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_embed_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_embed_def' do
-    it 'leaves embed as nil when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No embed
-      YAML
-      expect(eo.embed).to be_nil
-    end
-
-    it 'converts a string resource_name into a hash with resource_name key' do
-      # The referenced resource likely won't exist, but the structure should be set
-      eo = config_for(<<~YAML)
-        default:
-          embed: dynamic_model__some_resource
-      YAML
-
-      expect(eo.embed).to be_a Hash
-      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
-    end
-
-    it 'preserves a hash-style embed with resource_name' do
-      eo = config_for(<<~YAML)
-        default:
-          embed:
-            resource_name: dynamic_model__some_resource
-      YAML
-
-      expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
-    end
-
-    it 'warns when the embedded resource does not exist' do
-      eo = config_for(<<~YAML)
-        default:
-          embed:
-            resource_name: dynamic_model__nonexistent_model
-      YAML
-
-      expect(eo.config_warnings).not_to be_empty
-      warn = eo.config_warnings.find { |w| w[:type] == :embed }
-      expect(warn).to be_present
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_references_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_references_def' do
-    it 'leaves references as nil when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No references
-      YAML
-      expect(eo.references).to be_nil
-    end
-
-    it 'converts a hash-style references, singularizing keys' do
-      eo = config_for(<<~YAML)
-        default:
-          references:
-            player_infos:
-              label: Player Info Ref
-      YAML
-
-      # Keys should be singularized
-      expect(eo.references).to be_a Hash
-      ref_keys = eo.references.keys
-      # The key should wrap the reference as { singular_key => config }
-      ref_keys.each do |k|
-        inner = eo.references[k]
-        expect(inner).to be_a Hash
-      end
-    end
-
-    it 'converts an array-style references to a hash' do
-      eo = config_for(<<~YAML)
-        default:
-          references:
-            - player_infos:
-                label: Player Info Ref
-      YAML
-
-      expect(eo.references).to be_a Hash
-    end
-
-    it 'warns when a referenced model does not exist' do
-      eo = config_for(<<~YAML)
-        default:
-          references:
-            nonexistent_model_xyz:
-              label: Bad Reference
-      YAML
-
-      # Should generate a warning (not an error, since order of imports may cause this)
-      has_warning = eo.config_warnings.any? { |w| w[:type] == :references }
-      # May also just silently skip if to_class is nil; check references is cleaned up
-      expect(eo.references).to be_a Hash
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_save_triggers
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_save_triggers' do
-    it 'defaults save_trigger to a SaveTrigger with blank TriggerTasks' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No save triggers
-      YAML
-
-      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
-      expect(eo.save_trigger[:on_upload]).to be_a Hash
-      expect(eo.save_trigger[:on_upload]).to be_blank
-      expect(eo.save_trigger[:on_disable]).to be_a Hash
-      expect(eo.save_trigger[:on_disable]).to be_blank
-    end
-
-    it 'cascades on_save to on_create and on_update as array defaults' do
-      eo = config_for(<<~YAML)
-        default:
-          save_trigger:
-            on_save:
-              notify:
-                type: email
-      YAML
-
-      expect(eo.save_trigger[:on_create]).to be_an Array
-      expect(eo.save_trigger[:on_update]).to be_an Array
-      expect(eo.save_trigger[:on_create].length).to eq 1
-      expect(eo.save_trigger[:on_update].length).to eq 1
-    end
-
-    it 'appends on_save triggers to existing on_create and on_update' do
-      eo = config_for(<<~YAML)
-        default:
-          save_trigger:
-            on_save:
-              notify:
-                type: email
-            on_create:
-              create_action:
-                type: special
-      YAML
-
-      # on_create should have both on_save and its own trigger
-      expect(eo.save_trigger[:on_create]).to be_an Array
-      expect(eo.save_trigger[:on_create].length).to eq 2
-      # on_update should only have on_save trigger
-      expect(eo.save_trigger[:on_update]).to be_an Array
-      expect(eo.save_trigger[:on_update].length).to eq 1
-    end
-
-    it 'reports an error for invalid trigger keys' do
-      eo = config_for(<<~YAML)
-        default:
-          save_trigger:
-            on_invalid_trigger:
-              something: true
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :save_trigger }
-      expect(err).to be_present
-    end
-
-    it 'symbolizes save_trigger keys' do
-      eo = config_for(<<~YAML)
-        default:
-          save_trigger:
-            on_save:
-              notify:
-                type: email
-      YAML
-      expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
-      expect(eo.save_trigger.on_create).to be_a OptionConfigs::ExtraOptionConfigs::TriggerTasks
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_batch_triggers
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_batch_triggers' do
-    it 'defaults batch_trigger to a BatchTrigger with blank on_record TriggerTasks' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No batch triggers
-      YAML
-
-      expect(eo.batch_trigger).to be_a OptionConfigs::ExtraOptionConfigs::BatchTrigger
-      expect(eo.batch_trigger[:on_record]).to be_a Hash
-      expect(eo.batch_trigger[:on_record]).to be_blank
-    end
-
-    it 'preserves batch_trigger configuration and symbolizes keys' do
-      eo = config_for(<<~YAML)
-        default:
-          batch_trigger:
-            on_record:
-              action: process
-      YAML
-
-      expect(eo.batch_trigger[:on_record]).to be_a Hash
-      expect(eo.batch_trigger[:on_record]).to eq(action: 'process')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_config_triggers
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_config_triggers' do
-    it 'defaults config_trigger to a ConfigTrigger with empty on_define TriggerTasks' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No config triggers
-      YAML
-
-      expect(eo.config_trigger).to be_a OptionConfigs::ExtraOptionConfigs::ConfigTrigger
-      expect(eo.config_trigger[:on_define]).to be_an Array
-      expect(eo.config_trigger[:on_define]).to be_blank
-    end
-
-    it 'wraps on_define in an array if it is not already an array' do
-      eo = config_for(<<~YAML)
-        default:
-          config_trigger:
-            on_define:
-              action: do_something
-      YAML
-
-      expect(eo.config_trigger[:on_define]).to be_an Array
-      expect(eo.config_trigger[:on_define].length).to eq 1
-    end
-
-    it 'preserves on_define as an array if already provided' do
-      eo = config_for(<<~YAML)
-        default:
-          config_trigger:
-            on_define:
-              - action: first
-              - action: second
-      YAML
-
-      expect(eo.config_trigger[:on_define]).to be_an Array
-      expect(eo.config_trigger[:on_define].length).to eq 2
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_preset_fields
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_preset_fields' do
-    it 'defaults preset_fields to a blank PresetFields instance' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No presets
-      YAML
-      expect(eo.preset_fields).to be_blank
-    end
-
-    it 'preserves and symbolizes preset_fields' do
-      eo = config_for(<<~YAML)
-        default:
-          preset_fields:
-            test1: default_value
-            test2: another_value
-      YAML
-      expect(eo.preset_fields.symbolize_keys).to eq(test1: 'default_value', test2: 'another_value')
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_set_variables_def
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_set_variables_def' do
-    it 'defaults set_variables to a blank SetVariable when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No variables
-      YAML
-      expect(eo.set_variables).to be_nil
-    end
-
-    it 'preserves valid set_variables array entries' do
-      eo = config_for(<<~YAML)
-        default:
-          set_variables:
-            - name: var1
-              value: val1
-            - name: var2
-              value: val2
-              if:
-                always: true
-      YAML
-
-      expect(eo.set_variables).to be_an Array
-      expect(eo.set_variables.length).to eq 2
-      expect(eo.set_variables[0][:name]).to eq 'var1'
-      expect(eo.set_variables[0][:value]).to eq 'val1'
-      expect(eo.set_variables[1][:name]).to eq 'var2'
-      expect(eo.set_variables[1][:if]).to be_present
-    end
-
-    it 'reports an error and empties when set_variables is not an array' do
-      eo = config_for(<<~YAML)
-        default:
-          set_variables:
-            name: var1
-            value: val1
-      YAML
-
-      expect(eo.set_variables).to eq []
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :set_variables }
-      expect(err).to be_present
-    end
-
-    it 'filters out invalid entries missing name or value keys' do
-      eo = config_for(<<~YAML)
-        default:
-          set_variables:
-            - name: valid_var
-              value: valid_val
-            - no_name_key: invalid
-      YAML
-
-      expect(eo.set_variables).to be_an Array
-      expect(eo.set_variables.length).to eq 1
-      expect(eo.set_variables[0][:name]).to eq 'valid_var'
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # clean_field_configs
-  # ──────────────────────────────────────────────────────────────
-  describe '#clean_field_configs' do
-    it 'defaults field_configs to an empty hash when not specified' do
-      eo = config_for(<<~YAML)
-        default:
-          label: No field configs
-      YAML
-      expect(eo.field_configs).to eq({})
-    end
-
-    it 'merges field_configs into the standalone configs (caption_before, labels, etc.)' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-          field_configs:
-            test1:
-              caption_before: Caption for test1
-              labels: Label for test1
-            test2:
-              show_if:
-                test1: some_value
-      YAML
-
-      # field_configs should merge caption_before into the standalone caption_before
-      expect(eo.caption_before[:test1]).to be_present
-      # field_configs should merge labels into standalone labels
-      expect(eo.labels[:test1]).to eq 'Label for test1'
-      # field_configs should merge show_if into standalone show_if
-      expect(eo.show_if[:test2]).to eq(test1: 'some_value')
-    end
-
-    it 'reports an error when field_configs references fields not in the field list' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_configs:
-            nonexistent_field:
-              labels: Some label
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :field_configs }
-      expect(err).to be_present
-    end
-
-    it 'reports an error when field_configs contains invalid config keys' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_configs:
-            test1:
-              invalid_key: some value
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :field_configs }
-      expect(err).to be_present
-    end
-
-    it 'reports an error when a field config value is not a Hash' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_configs:
-            test1: not_a_hash
-      YAML
-
-      expect(eo.config_errors).not_to be_empty
-      err = eo.config_errors.find { |e| e[:type] == :field_configs }
-      expect(err).to be_present
-    end
-
-    it 'stores raw_field_configs as a deep clone before standalone defs are merged' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          field_configs:
-            test1:
-              labels: Raw label
-          labels:
-            test1: Standalone label
-      YAML
-
-      # raw_field_configs should be a deep copy of field_configs before standalone merge
-      expect(eo.raw_field_configs).to be_a Hash
-      expect(eo.raw_field_configs[:test1]).to be_a Hash
-      # Modifying raw_field_configs should not affect field_configs
-      original_fc = eo.field_configs[:test1].dup
-      eo.raw_field_configs[:test1][:labels] = 'Modified'
-      expect(eo.field_configs[:test1]).to eq original_fc
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # add_field_configs_from_standalone_defs
-  # ──────────────────────────────────────────────────────────────
-  describe '#add_field_configs_from_standalone_defs' do
-    it 'merges standalone configs back into field_configs for valid fields' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-          labels:
-            test1: Standalone Label 1
-          caption_before:
-            test2: Standalone caption
-      YAML
-
-      expect(eo.field_configs[:test1]).to include(labels: 'Standalone Label 1')
-      expect(eo.field_configs[:test2]).to be_a Hash
-      expect(eo.field_configs[:test2]).to have_key(:caption_before)
-    end
-
-    it 'does not include standalone configs for fields not in the field list' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-          labels:
-            test1: Included
-            not_a_field: Excluded
-      YAML
-
-      expect(eo.field_configs).not_to have_key(:not_a_field)
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # resource_name and resource_item_name initialization
-  # ──────────────────────────────────────────────────────────────
-  describe 'resource_name initialization' do
-    it 'sets resource_name from config_obj and option name' do
-      eo = config_for(<<~YAML)
-        my_option:
-          label: Test
-      YAML
-
-      expect(eo.resource_name).to include('my_option')
-      expect(eo.resource_item_name).to eq eo.resource_name
-    end
-  end
-
-  # ──────────────────────────────────────────────────────────────
-  # Integration: full initialization sequence
-  # ──────────────────────────────────────────────────────────────
-  describe 'full initialization with multiple configs' do
-    it 'initializes all clean_ methods in sequence without errors for valid config' do
-      eo = config_for(<<~YAML)
-        default:
-          fields:
-            - test1
-            - test2
-          label: Full Test
-          labels:
-            test1: Test One
-            test2: Test Two
-          caption_before:
-            test1: Caption One
-          view_options:
-            data_attribute: test1
-          save_action:
-            on_save:
-              label: Saved
-          field_options:
-            test1:
-              no_downcase: true
-          preset_fields:
-            test1: preset_val
-      YAML
-
-      expect(eo.config_errors).to be_empty
-      expect(eo.label).to eq 'Full Test'
-      expect(eo.fields).to eq %w[test1 test2]
-      expect(eo.labels.symbolize_keys).to eq(test1: 'Test One', test2: 'Test Two')
-      expect(eo.caption_before[:test1]).to respond_to(:[])
-      expect(eo.caption_before[:test1][:caption]).to be_present
-      expect(eo.view_options[:data_attribute]).to eq 'test1'
-      expect(eo.save_action[:on_create][:label]).to eq 'Saved'
-      expect(eo.field_options[:test1][:no_downcase]).to eq true
-      expect(eo.preset_fields[:test1]).to eq 'preset_val'
-    end
-
-    it 'handles multiple named option configs from a single definition' do
-      configs = all_configs_for(<<~YAML)
-        option_a:
-          label: Option A
-          fields:
-            - test1
-        option_b:
-          label: Option B
-          fields:
-            - test2
-      YAML
-
-      # parse_config may produce additional configs from _comments processing
-      # but our named configs should be present
-      names = configs.map(&:name)
-      expect(names).to include(:option_a)
-      expect(names).to include(:option_b)
-      expect(configs.length).to be >= 2
-    end
-  end
-end
diff --git a/spec/support/extra_option_configs_support.rb b/spec/support/extra_option_configs_support.rb
new file mode 100644
index 0000000000..e946dc353d
--- /dev/null
+++ b/spec/support/extra_option_configs_support.rb
@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Shared helpers and constants for ExtraOptionConfigs specs.
+# Include this module in any spec that tests configuration classes.
+module ExtraOptionConfigsSupport
+  # All expected config classes with their managed attributes.
+  # Registry key must match the ExtraOptions attribute name.
+  # Class names are singular (SaveTrigger not SaveTriggers).
+  # AccessIf is split into CreatableIf, EditableIf, ShowableIf.
+  EXPECTED_CONFIG_CLASSES = {
+    fields: :Fields,
+    label: :Label,
+    caption_before: :CaptionBefore,
+    dialog_before: :DialogBefore,
+    labels: :Labels,
+    show_if: :ShowIf,
+    save_action: :SaveAction,
+    view_options: :ViewOptions,
+    db_configs: :DbConfigs,
+    creatable_if: :CreatableIf,
+    editable_if: :EditableIf,
+    showable_if: :ShowableIf,
+    valid_if: :ValidIf,
+    filestore: :Filestore,
+    field_options: :FieldOptions,
+    embed: :Embed,
+    references_config: :References,
+    save_trigger: :SaveTrigger,
+    batch_trigger: :BatchTrigger,
+    config_trigger: :ConfigTrigger,
+    preset_fields: :PresetFields,
+    set_variables: :SetVariable,
+    field_configs: :FieldConfigs
+  }.freeze
+
+  # Config classes that use the field-keyed BaseConfiguration pattern
+  FIELD_KEYED_CLASSES = %i[CaptionBefore Labels DialogBefore ShowIf FieldOptions DbConfigs PresetFields].freeze
+
+  # Config classes converted to BaseConfiguration with typed or direct attributes
+  TYPED_CONFIG_CLASSES = %i[
+    BatchTrigger SaveTrigger ViewOptions Filestore ConfigTrigger SaveAction ValidIf SetVariable
+    Fields Label CreatableIf EditableIf ShowableIf Embed FieldConfigs
+  ].freeze
+
+  # Config classes that use source_attribute to read input from a different ExtraOptions attribute
+  SOURCE_ATTRIBUTE_CLASSES = %i[References].freeze
+
+  # Helper: update the DynamicModel with given YAML options and return the first option config
+  def config_for(yaml)
+    @dm.update!(options: yaml, current_admin: @admin)
+    @dm.option_configs.first
+  end
+
+  # Helper: return all option configs for the given YAML
+  def all_configs_for(yaml)
+    @dm.update!(options: yaml, current_admin: @admin)
+    @dm.option_configs
+  end
+end

From b5543f3c39eb07bda5123386049de895a15770b9 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 03/16] Added source_attribute pattern for Embed and
 ESignConfig with configure_attributes for input-only fields

---
 .../option_configs/activity_log_options.rb    |  4 +-
 .../extra_option_configs/e_sign_config.rb     | 58 ++++++++++++--
 .../extra_option_configs/embed.rb             | 28 +++++--
 app/models/option_configs/extra_options.rb    |  4 +-
 .../activity_log_options_spec.rb              | 14 ++--
 .../e_sign_config_spec.rb                     | 80 ++++++++++++++++++-
 .../extra_option_configs/embed_spec.rb        | 58 ++++++++++++--
 .../extra_option_configs/registry_spec.rb     | 18 ++++-
 spec/support/extra_option_configs_support.rb  |  6 +-
 9 files changed, 229 insertions(+), 41 deletions(-)

diff --git a/app/models/option_configs/activity_log_options.rb b/app/models/option_configs/activity_log_options.rb
index 3a8093f9a2..694adf54d7 100644
--- a/app/models/option_configs/activity_log_options.rb
+++ b/app/models/option_configs/activity_log_options.rb
@@ -12,13 +12,13 @@ class ActivityLogOptions < ExtraOptions
 
     def self.config_class_registry
       super.merge(
-        e_sign: ExtraOptionConfigs::ESignConfig,
+        e_sign_config: ExtraOptionConfigs::ESignConfig,
         nfs_store: ExtraOptionConfigs::NfsStoreConfig
       )
     end
 
     def self.add_key_attributes
-      []
+      %i[e_sign]
     end
 
     attr_accessor(*key_attributes)
diff --git a/app/models/option_configs/extra_option_configs/e_sign_config.rb b/app/models/option_configs/extra_option_configs/e_sign_config.rb
index 67a7ecc14c..38173186b4 100644
--- a/app/models/option_configs/extra_option_configs/e_sign_config.rb
+++ b/app/models/option_configs/extra_option_configs/e_sign_config.rb
@@ -3,14 +3,28 @@
 module OptionConfigs
   module ExtraOptionConfigs
     # Configuration class for e-signature definitions.
-    # Migrated from ActivityLogOptions#clean_e_sign_def (issue #986).
     #
-    # Transforms e_sign document_reference structure: wraps in {item: ...},
-    # singularizes keys, and resolves model references.
+    # Uses the source_attribute pattern: the registry key is :e_sign_config,
+    # but the raw input is read from :e_sign (an add_key_attribute on ActivityLogOptions).
+    # After processing:
+    # - extra_options.e_sign = enriched hash (runtime code consumes this)
+    # - extra_options.e_sign_config = this ESignConfig instance (input-only attributes)
     #
-    # The processed hash is stored back on the parent ExtraOptions (not the object).
+    # Handles:
+    # - Wrapping document_reference in {item: ...}
+    # - Singularizing keys within document_reference entries
+    # - Resolving model references and enriching with class metadata
     class ESignConfig < BaseConfiguration
       configure_direct :e_sign, type: :hash
+      configure_attributes %i[create_document auto_create_document document_reference title intro]
+
+      # Keys added by prepare_config within document_reference model entries
+      # that are not part of admin input.
+      COMPUTED_KEYS = %i[to_record_label no_master_association to_model_name_us].freeze
+
+      def self.source_attribute
+        :e_sign
+      end
 
       def self.store_processed_value?
         true
@@ -49,8 +63,42 @@ def self.prepare_config(raw, _parent)
         raw
       end
 
+      # Store enriched hash on the direct attribute and assign input-only
+      # configured attributes for round-trip serialization.
+      # @return [void]
       def setup_named_configurations
-        self.e_sign = hash_configuration
+        self.e_sign = hash_configuration.presence
+        return unless e_sign
+
+        # Assign top-level input attributes
+        e_sign.each do |k, v|
+          next if k == :document_reference
+
+          send("#{k}=", v) if respond_to?("#{k}=")
+        end
+
+        # Store input-only document_reference (strip computed keys from nested model entries)
+        return unless e_sign[:document_reference]
+
+        self.document_reference = strip_doc_ref_computed_keys(e_sign[:document_reference])
+      end
+
+      private
+
+      # Strip computed keys from each model entry nested within document_reference.
+      # Structure: { item: { model_name: { from: ..., to_record_label: ..., ... } } }
+      # @param doc_ref [Hash] the document_reference hash
+      # @return [Hash] document_reference with computed keys removed from model entries
+      def strip_doc_ref_computed_keys(doc_ref)
+        doc_ref.transform_values do |group|
+          next group unless group.is_a?(Hash)
+
+          group.transform_values do |entry|
+            next entry unless entry.is_a?(Hash)
+
+            entry.except(*COMPUTED_KEYS)
+          end
+        end
       end
     end
   end
diff --git a/app/models/option_configs/extra_option_configs/embed.rb b/app/models/option_configs/extra_option_configs/embed.rb
index 165b9292d8..ee6350d9e7 100644
--- a/app/models/option_configs/extra_option_configs/embed.rb
+++ b/app/models/option_configs/extra_option_configs/embed.rb
@@ -3,17 +3,28 @@
 module OptionConfigs
   module ExtraOptionConfigs
     # Configuration class for embedded resource definitions.
-    # Converted from ConfigBase to BaseConfiguration pattern.
+    #
+    # Uses the source_attribute pattern: the registry key is :embed_config,
+    # but the raw input is read from :embed (a base_key_attribute).
+    # After processing:
+    # - extra_options.embed = enriched hash (runtime code consumes this)
+    # - extra_options.embed_config = this Embed instance (input-only attributes)
     #
     # Handles:
     # - Converting 'default_embed_resource' string to resource_name hash
     # - Converting plain string to { resource_name: string } hash
     # - Looking up the resource model definition
     # - Warning when embedded resource does not exist
-    #
-    # The processed hash is stored back on the parent ExtraOptions (not the object).
     class Embed < BaseConfiguration
       configure_direct :embed, type: :hash
+      configure_attributes %i[resource_name resource_id limit]
+
+      # Key added by prepare_config that is not part of admin input.
+      COMPUTED_KEYS = %i[resource_model_def].freeze
+
+      def self.source_attribute
+        :embed
+      end
 
       def self.store_processed_value?
         true
@@ -53,8 +64,8 @@ def self.prepare_config(raw, parent)
         emb
       end
 
-      # Store the embed hash value.
-      # Handles string input by converting to resource_name hash.
+      # Store enriched hash on the direct attribute and assign input-only
+      # configured attributes for round-trip serialization.
       # @return [void]
       def setup_named_configurations
         raw = hash_configuration
@@ -62,9 +73,12 @@ def setup_named_configurations
                        { resource_name: raw }
                      elsif raw.is_a?(Hash) && raw.present?
                        raw
-                     else
-                       raw.presence
                      end
+        return unless embed
+
+        embed.except(*COMPUTED_KEYS).each do |k, v|
+          send("#{k}=", v) if respond_to?("#{k}=")
+        end
       end
 
       private
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 4ea6801d38..8c4a4994d3 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -34,7 +34,7 @@ def self.config_class_registry
         valid_if: ExtraOptionConfigs::ValidIf,
         filestore: ExtraOptionConfigs::Filestore,
         field_options: ExtraOptionConfigs::FieldOptions,
-        embed: ExtraOptionConfigs::Embed,
+        embed_config: ExtraOptionConfigs::Embed,
         references_config: ExtraOptionConfigs::References,
         save_trigger: ExtraOptionConfigs::SaveTrigger,
         batch_trigger: ExtraOptionConfigs::BatchTrigger,
@@ -48,7 +48,7 @@ def self.base_key_attributes
       %i[
         name config_obj resource_name resource_item_name add_reference_if
         button_label orig_config show_if_condition_strings raw_field_configs
-        references
+        references embed
       ]
     end
 
diff --git a/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb b/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
index c23510d265..023e419b3e 100644
--- a/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/activity_log_options_spec.rb
@@ -27,10 +27,10 @@
                         'Expected ActivityLogOptions.config_class_registry to include :nfs_store'
   end
 
-  it 'extends parent registry with e_sign' do
+  it 'extends parent registry with e_sign_config' do
     registry = OptionConfigs::ActivityLogOptions.config_class_registry
-    expect(registry).to have_key(:e_sign),
-                        'Expected ActivityLogOptions.config_class_registry to include :e_sign'
+    expect(registry).to have_key(:e_sign_config),
+                        'Expected ActivityLogOptions.config_class_registry to include :e_sign_config'
   end
 
   it 'maps nfs_store to NfsStoreConfig class' do
@@ -38,13 +38,13 @@
     expect(registry[:nfs_store]).to eq(OptionConfigs::ExtraOptionConfigs::NfsStoreConfig)
   end
 
-  it 'maps e_sign to ESignConfig class' do
+  it 'maps e_sign_config to ESignConfig class' do
     registry = OptionConfigs::ActivityLogOptions.config_class_registry
-    expect(registry[:e_sign]).to eq(OptionConfigs::ExtraOptionConfigs::ESignConfig)
+    expect(registry[:e_sign_config]).to eq(OptionConfigs::ExtraOptionConfigs::ESignConfig)
   end
 
-  it 'returns empty add_key_attributes' do
-    expect(OptionConfigs::ActivityLogOptions.add_key_attributes).to eq([])
+  it 'returns add_key_attributes containing :e_sign' do
+    expect(OptionConfigs::ActivityLogOptions.add_key_attributes).to eq([:e_sign])
   end
 
   it 'does not define clean_nfs_store_def as instance method' do
diff --git a/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb b/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
index 1b0300c629..682083cdcc 100644
--- a/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/e_sign_config_spec.rb
@@ -4,8 +4,10 @@
 require './db/table_generators/dynamic_models_table'
 
 # Tests for ESignConfig configuration class.
-# Verifies document_reference wrapping, key singularization,
-# model reference resolution, and integration with ActivityLogOptions registry.
+# Verifies source_attribute pattern, configure_attributes for input-only fields,
+# COMPUTED_KEYS within document_reference, document_reference wrapping,
+# key singularization, model reference resolution, and integration
+# with ActivityLogOptions registry.
 RSpec.describe 'ExtraOptionConfigs::ESignConfig', type: :model do
   include MasterSupport
   include ModelSupport
@@ -28,13 +30,22 @@
       expect(klass).to be < OptionConfigs::ExtraOptionConfigs::BaseConfiguration
     end
 
-    it 'stores processed value' do
-      expect(klass.store_processed_value?).to be true
+    it 'declares source_attribute :e_sign' do
+      expect(klass.source_attribute).to eq :e_sign
     end
 
     it 'declares configure_direct with type :hash' do
       expect(klass.option_types[:direct]).to include(:e_sign)
     end
+
+    it 'declares configure_attributes for input-only fields' do
+      expect(klass.option_types[:simple]).to include(:create_document, :auto_create_document,
+                                                     :document_reference, :title, :intro)
+    end
+
+    it 'defines COMPUTED_KEYS for enrichment-only keys within document_reference' do
+      expect(klass::COMPUTED_KEYS).to eq %i[to_record_label no_master_association to_model_name_us]
+    end
   end
 
   describe 'prepare_config' do
@@ -77,4 +88,65 @@
       expect(result).to be_nil
     end
   end
+
+  describe 'initialization with configure_attributes' do
+    it 'assigns top-level input attributes' do
+      raw = {
+        create_document: true,
+        auto_create_document: false,
+        title: 'Test Title',
+        intro: 'Test Intro',
+        document_reference: { item: { player_contact: { from: :master } } }
+      }
+      instance = klass.new(raw)
+      expect(instance.create_document).to be true
+      expect(instance.auto_create_document).to be false
+      expect(instance.title).to eq 'Test Title'
+      expect(instance.intro).to eq 'Test Intro'
+    end
+
+    it 'stores input-only document_reference with computed keys stripped' do
+      raw = {
+        document_reference: {
+          item: {
+            player_contact: {
+              from: :master,
+              label: 'My Label',
+              to_record_label: 'COMPUTED',
+              no_master_association: false,
+              to_model_name_us: 'player_contact'
+            }
+          }
+        }
+      }
+      instance = klass.new(raw)
+      doc_ref = instance.document_reference
+      entry = doc_ref[:item][:player_contact]
+      expect(entry).to have_key(:from)
+      expect(entry).to have_key(:label)
+      expect(entry).not_to have_key(:to_record_label)
+      expect(entry).not_to have_key(:no_master_association)
+      expect(entry).not_to have_key(:to_model_name_us)
+    end
+
+    it 'stores enriched hash (with computed keys) on e_sign direct attribute' do
+      raw = {
+        title: 'Test',
+        document_reference: {
+          item: {
+            player_contact: {
+              from: :master,
+              to_record_label: 'COMPUTED',
+              to_model_name_us: 'player_contact'
+            }
+          }
+        }
+      }
+      instance = klass.new(raw)
+      enriched = instance.e_sign
+      entry = enriched[:document_reference][:item][:player_contact]
+      expect(entry[:to_record_label]).to eq 'COMPUTED'
+      expect(entry[:to_model_name_us]).to eq 'player_contact'
+    end
+  end
 end
diff --git a/spec/models/option_configs/extra_option_configs/embed_spec.rb b/spec/models/option_configs/extra_option_configs/embed_spec.rb
index 8e8a1efb1c..6c14c2aa49 100644
--- a/spec/models/option_configs/extra_option_configs/embed_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/embed_spec.rb
@@ -4,8 +4,9 @@
 require './db/table_generators/dynamic_models_table'
 
 # Tests for Embed configuration class.
-# Verifies resource_name handling, validate callbacks, and integration through
-# ExtraOptions initialization (clean_embed_def behavior).
+# Verifies source_attribute pattern, configure_attributes, COMPUTED_KEYS,
+# resource_name handling, validate callbacks, and integration through
+# ExtraOptions initialization with enriched hash and instance separation.
 RSpec.describe 'ExtraOptionConfigs::Embed', type: :model do
   include MasterSupport
   include ModelSupport
@@ -28,13 +29,21 @@
       expect(klass.ancestors).to include(OptionConfigs::ExtraOptionConfigs::BaseConfiguration)
     end
 
-    it 'does not inherit from ConfigBase' do
-      expect(klass.ancestors).not_to include(OptionConfigs::ExtraOptionConfigs::ConfigBase)
+    it 'declares source_attribute :embed' do
+      expect(klass.source_attribute).to eq :embed
     end
 
     it 'declares configure_direct with type :hash' do
       expect(klass.option_types[:direct]).to include(:embed)
     end
+
+    it 'declares configure_attributes for input-only fields' do
+      expect(klass.option_types[:simple]).to include(:resource_name, :resource_id, :limit)
+    end
+
+    it 'defines COMPUTED_KEYS for enrichment-only keys' do
+      expect(klass::COMPUTED_KEYS).to eq %i[resource_model_def]
+    end
   end
 
   describe 'initialization' do
@@ -43,9 +52,17 @@
       expect(instance.embed[:resource_name]).to eq 'some_resource'
     end
 
-    it 'stores resource_name from hash input' do
-      instance = klass.new(resource_name: 'some_resource')
-      expect(instance.embed[:resource_name]).to eq 'some_resource'
+    it 'assigns input-only configure_attributes from hash input' do
+      instance = klass.new(resource_name: 'some_resource', resource_id: 42, limit: 1)
+      expect(instance.resource_name).to eq 'some_resource'
+      expect(instance.resource_id).to eq 42
+      expect(instance.limit).to eq 1
+    end
+
+    it 'does not assign computed keys to configure_attributes' do
+      instance = klass.new(resource_name: 'test', resource_model_def: { model: 'fake' })
+      expect(instance.embed[:resource_model_def]).to eq({ model: 'fake' })
+      expect(instance).not_to respond_to(:resource_model_def)
     end
 
     it 'returns blank when initialized with nil' do
@@ -93,7 +110,7 @@
       expect(eo.embed).to be_nil
     end
 
-    it 'converts a string resource_name into a hash with resource_name key' do
+    it 'converts a string resource_name into an enriched hash with resource_name and resource_model_def' do
       eo = config_for(<<~YAML)
         default:
           embed: dynamic_model__some_resource
@@ -101,6 +118,31 @@
 
       expect(eo.embed).to be_a Hash
       expect(eo.embed[:resource_name]).to eq 'dynamic_model__some_resource'
+      expect(eo.embed).to have_key(:resource_model_def)
+    end
+
+    it 'stores the Embed instance at embed_config' do
+      eo = config_for(<<~YAML)
+        default:
+          embed: dynamic_model__some_resource
+      YAML
+
+      expect(eo.embed_config).to be_a(klass)
+      expect(eo.embed_config.resource_name).to eq 'dynamic_model__some_resource'
+    end
+
+    it 'embed_config has input-only attributes without computed keys' do
+      eo = config_for(<<~YAML)
+        default:
+          embed:
+            resource_name: dynamic_model__some_resource
+            limit: 1
+      YAML
+
+      instance = eo.embed_config
+      expect(instance.resource_name).to eq 'dynamic_model__some_resource'
+      expect(instance.limit).to eq 1
+      expect(instance).not_to respond_to(:resource_model_def)
     end
 
     it 'preserves a hash-style embed with resource_name' do
diff --git a/spec/models/option_configs/extra_option_configs/registry_spec.rb b/spec/models/option_configs/extra_option_configs/registry_spec.rb
index 9a283d7811..e1a0c00bc1 100644
--- a/spec/models/option_configs/extra_option_configs/registry_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/registry_spec.rb
@@ -82,14 +82,15 @@
     it 'base_key_attributes does not overlap config class attributes (except source_attribute keys)' do
       base = OptionConfigs::ExtraOptions.base_key_attributes
       config_attrs = OptionConfigs::ExtraOptions.config_class_attributes
-      # source_attribute classes read from a base_key_attribute, so :references
-      # appears in base_key_attributes but not in config_class_attributes
+      # source_attribute classes read from a base_key_attribute, so :references and :embed
+      # appear in base_key_attributes but not in config_class_attributes
       overlap = base & config_attrs
       expect(overlap).to be_empty,
                          "base_key_attributes should not overlap config_class_attributes, but found: #{overlap}"
     end
 
-    it 'base_key_attributes includes source_attribute keys for source_attribute classes' do
+    it 'base_key_attributes or add_key_attributes includes source_attribute keys for source_attribute classes' do
+      # ExtraOptions source_attribute classes (e.g. References, Embed)
       base = OptionConfigs::ExtraOptions.base_key_attributes
       registry = OptionConfigs::ExtraOptions.config_class_registry
       registry.each do |_key, config_class|
@@ -99,6 +100,17 @@
                          "Expected base_key_attributes to include :#{config_class.source_attribute} " \
                          "for source_attribute class #{config_class.name}"
       end
+
+      # ActivityLogOptions source_attribute classes (e.g. ESignConfig)
+      alo_registry = OptionConfigs::ActivityLogOptions.config_class_registry
+      alo_all_attrs = OptionConfigs::ActivityLogOptions.key_attributes
+      alo_registry.each do |_key, config_class|
+        next unless config_class.respond_to?(:source_attribute) && config_class.source_attribute
+
+        expect(alo_all_attrs).to include(config_class.source_attribute),
+                                  "Expected ActivityLogOptions key_attributes to include :#{config_class.source_attribute} " \
+                                  "for source_attribute class #{config_class.name}"
+      end
     end
 
     it 'key_attributes includes both base and config class attributes' do
diff --git a/spec/support/extra_option_configs_support.rb b/spec/support/extra_option_configs_support.rb
index e946dc353d..3a3b43d8b8 100644
--- a/spec/support/extra_option_configs_support.rb
+++ b/spec/support/extra_option_configs_support.rb
@@ -23,7 +23,7 @@ module ExtraOptionConfigsSupport
     valid_if: :ValidIf,
     filestore: :Filestore,
     field_options: :FieldOptions,
-    embed: :Embed,
+    embed_config: :Embed,
     references_config: :References,
     save_trigger: :SaveTrigger,
     batch_trigger: :BatchTrigger,
@@ -39,11 +39,11 @@ module ExtraOptionConfigsSupport
   # Config classes converted to BaseConfiguration with typed or direct attributes
   TYPED_CONFIG_CLASSES = %i[
     BatchTrigger SaveTrigger ViewOptions Filestore ConfigTrigger SaveAction ValidIf SetVariable
-    Fields Label CreatableIf EditableIf ShowableIf Embed FieldConfigs
+    Fields Label CreatableIf EditableIf ShowableIf FieldConfigs
   ].freeze
 
   # Config classes that use source_attribute to read input from a different ExtraOptions attribute
-  SOURCE_ATTRIBUTE_CLASSES = %i[References].freeze
+  SOURCE_ATTRIBUTE_CLASSES = %i[References Embed ESignConfig].freeze
 
   # Helper: update the DynamicModel with given YAML options and return the first option config
   def config_for(yaml)

From c59c44680945ba2ba36f2aa5d265d50ffa4d855b Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 04/16] Added NamedConfiguration to DbConfigs for column config
 entries - fixes #986

---
 .../extra_option_configs/db_configs.rb        |  7 ++-
 .../extra_option_configs/db_configs_spec.rb   | 53 ++++++++++++++++---
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/app/models/option_configs/extra_option_configs/db_configs.rb b/app/models/option_configs/extra_option_configs/db_configs.rb
index 1ef9a50873..20c5a78db9 100644
--- a/app/models/option_configs/extra_option_configs/db_configs.rb
+++ b/app/models/option_configs/extra_option_configs/db_configs.rb
@@ -6,11 +6,14 @@ module ExtraOptionConfigs
     # Extracted from ExtraOptions#clean_db_configs_def
     #
     # Values are column configuration hashes keyed by column name.
+    # Each entry defines database column overrides (type, array, index, encrypted).
     # The mutation of config_obj.db_columns is handled by ExtraOptions
     # after this config class runs.
     class DbConfigs < BaseConfiguration
-      # No special processing needed — keys are already symbolized
-      # by parse_options_text's deep_symbolize_keys!
+      # Named configuration for a single column's database settings.
+      class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
+        configure_attributes %i[type array index encrypted]
+      end
     end
   end
 end
diff --git a/spec/models/option_configs/extra_option_configs/db_configs_spec.rb b/spec/models/option_configs/extra_option_configs/db_configs_spec.rb
index e516884af1..12068e4667 100644
--- a/spec/models/option_configs/extra_option_configs/db_configs_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/db_configs_spec.rb
@@ -4,7 +4,8 @@
 require './db/table_generators/dynamic_models_table'
 
 # Tests for DbConfigs configuration class.
-# Verifies field-keyed BaseConfiguration behavior and integration through
+# Verifies NamedConfiguration for column definitions (type, array, index, encrypted),
+# field-keyed BaseConfiguration behavior, and integration through
 # ExtraOptions initialization (clean_db_configs_def behavior).
 RSpec.describe 'ExtraOptionConfigs::DbConfigs', type: :model do
   include MasterSupport
@@ -23,11 +24,36 @@
 
   let(:klass) { OptionConfigs::ExtraOptionConfigs::DbConfigs }
 
+  describe 'class structure' do
+    it 'defines a NamedConfiguration inner class' do
+      expect(klass.const_defined?(:NamedConfiguration)).to be true
+    end
+
+    it 'NamedConfiguration declares column config attributes' do
+      nc = klass::NamedConfiguration
+      expect(nc.option_types[:simple]).to include(:type, :array, :index, :encrypted)
+    end
+  end
+
   describe 'initialization' do
-    it 'stores column configs directly' do
+    it 'creates NamedConfiguration entries for hash values' do
+      instance = klass.new(col1: { type: 'string', array: true })
+      expect(instance[:col1]).to be_a(klass::NamedConfiguration)
+      expect(instance[:col1].type).to eq 'string'
+      expect(instance[:col1].array).to be true
+    end
+
+    it 'stores non-hash values directly' do
       instance = klass.new(col1: 'type_a')
       expect(instance[:col1]).to eq 'type_a'
-      expect(instance.symbolize_keys).to eq(col1: 'type_a')
+    end
+
+    it 'symbolize_keys converts NamedConfiguration entries to plain hashes' do
+      instance = klass.new(col1: { type: 'string', encrypted: true })
+      result = instance.symbolize_keys
+      expect(result[:col1]).to be_a(Hash)
+      expect(result[:col1][:type]).to eq 'string'
+      expect(result[:col1][:encrypted]).to be true
     end
   end
 
@@ -44,7 +70,8 @@
       eo = config_for(<<~YAML)
         default:
           db_configs:
-            some_column: some_value
+            some_column:
+              type: string
       YAML
       expect(eo.db_configs.keys).to all(be_a Symbol)
     end
@@ -53,10 +80,24 @@
       eo = config_for(<<~YAML)
         default:
           db_configs:
-            some_column: some_value
+            some_column:
+              type: string
+      YAML
+
+      expect(@dm.db_columns).to eq(some_column: { type: 'string' })
+    end
+
+    it 'warns about unrecognized keys in column config' do
+      eo = config_for(<<~YAML)
+        default:
+          db_configs:
+            some_column:
+              type: string
+              bogus_key: invalid
       YAML
 
-      expect(@dm.db_columns).to eq(some_column: 'some_value')
+      expect(eo.db_configs[:some_column]).to be_a(klass::NamedConfiguration)
+      expect(eo.config_warnings).not_to be_empty
     end
   end
 end

From 71d791f0d42447424dbcad987bbdfc2cb4c4a488 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 05/16] Added NamedConfiguration to FieldOptions for per-field
 options - fixes #986

---
 .../base_named_configuration.rb               |  2 +-
 .../extra_option_configs/field_options.rb     | 12 ++++-
 .../field_options_spec.rb                     | 46 ++++++++++++++++++-
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/app/models/option_configs/base_named_configuration.rb b/app/models/option_configs/base_named_configuration.rb
index 5cbba29c92..c9ff215466 100644
--- a/app/models/option_configs/base_named_configuration.rb
+++ b/app/models/option_configs/base_named_configuration.rb
@@ -46,7 +46,7 @@ def dig(*keys)
     # @param other [Object] value to compare against
     # @return [Boolean]
     def ==(other)
-      return to_h == other if other.is_a?(Hash)
+      return filtered_hash == other if other.is_a?(Hash)
 
       super
     end
diff --git a/app/models/option_configs/extra_option_configs/field_options.rb b/app/models/option_configs/extra_option_configs/field_options.rb
index 568f83851f..8a250a472d 100644
--- a/app/models/option_configs/extra_option_configs/field_options.rb
+++ b/app/models/option_configs/extra_option_configs/field_options.rb
@@ -5,10 +5,18 @@ module ExtraOptionConfigs
     # Configuration class for field-level edit options.
     # Extracted from ExtraOptions#clean_field_options_def
     #
-    # Values are arbitrary option hashes keyed by field name.
+    # Values are per-field option hashes keyed by field name.
     # Handles converting edit_as.alt_options from Array to Hash.
     class FieldOptions < BaseConfiguration
-      # No NamedConfiguration — values are arbitrary option hashes
+      # Named configuration for a single field's options.
+      class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
+        configure_attributes %i[
+          include_blank pattern value blank_value preset_value blank_preset_value
+          active_value no_downcase view_original_case view_with_formats format
+          config edit_as calculate_with prompt use_app_type selected show_expanded
+          keep_label
+        ]
+      end
 
       # Override to preprocess alt_options arrays.
       def add_named_configuration(sym_key, value)
diff --git a/spec/models/option_configs/extra_option_configs/field_options_spec.rb b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
index 1a814eb3a1..d37c6990ab 100644
--- a/spec/models/option_configs/extra_option_configs/field_options_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
@@ -4,7 +4,8 @@
 require './db/table_generators/dynamic_models_table'
 
 # Tests for FieldOptions configuration class.
-# Verifies alt_options preprocessing and integration through
+# Verifies NamedConfiguration for per-field options (edit_as, value, pattern, etc.),
+# alt_options preprocessing, and integration through
 # ExtraOptions initialization (clean_field_options_def behavior).
 RSpec.describe 'ExtraOptionConfigs::FieldOptions', type: :model do
   include MasterSupport
@@ -23,7 +24,36 @@
 
   let(:klass) { OptionConfigs::ExtraOptionConfigs::FieldOptions }
 
+  describe 'class structure' do
+    it 'defines a NamedConfiguration inner class' do
+      expect(klass.const_defined?(:NamedConfiguration)).to be true
+    end
+
+    it 'NamedConfiguration declares field option attributes' do
+      nc = klass::NamedConfiguration
+      expected = %i[
+        include_blank pattern value blank_value preset_value blank_preset_value
+        active_value no_downcase view_original_case view_with_formats format
+        config edit_as calculate_with prompt use_app_type selected show_expanded
+        keep_label
+      ]
+      expected.each { |attr| expect(nc.option_types[:simple]).to include(attr) }
+    end
+  end
+
   describe 'initialization' do
+    it 'creates NamedConfiguration entries for hash values' do
+      instance = klass.new(field1: { no_downcase: true, pattern: '.+' })
+      expect(instance[:field1]).to be_a(klass::NamedConfiguration)
+      expect(instance[:field1].no_downcase).to be true
+      expect(instance[:field1].pattern).to eq '.+'
+    end
+
+    it 'stores non-hash values directly' do
+      instance = klass.new(field1: 'simple_value')
+      expect(instance[:field1]).to eq 'simple_value'
+    end
+
     it 'converts alt_options Array to Hash' do
       instance = klass.new(
         field1: { edit_as: { alt_options: %w[ChoiceA ChoiceB] } }
@@ -32,6 +62,20 @@
       expect(ao).to be_a Hash
       expect(ao[:ChoiceA]).to eq 'choicea'
     end
+
+    it 'symbolize_keys converts NamedConfiguration entries to plain hashes' do
+      instance = klass.new(field1: { no_downcase: true, value: 'x' })
+      result = instance.symbolize_keys
+      expect(result[:field1]).to be_a(Hash)
+      expect(result[:field1][:no_downcase]).to be true
+      expect(result[:field1][:value]).to eq 'x'
+    end
+
+    it 'warns about unrecognized keys in field config' do
+      instance = klass.new(field1: { no_downcase: true, bogus_key: 'bad' })
+      expect(instance[:field1]).to be_a(klass::NamedConfiguration)
+      expect(instance.config_warnings).not_to be_empty
+    end
   end
 
   describe 'ExtraOptions integration' do

From 24a998f1963be40e2baa97bdd9acef091885f801 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 06/16] Added Configurations class for top-level
 _configurations options - fixes #986

---
 .../extra_option_configs/configurations.rb    |  40 ++++++
 app/models/option_configs/extra_options.rb    |   4 +-
 .../configurations_spec.rb                    | 115 ++++++++++++++++++
 3 files changed, 158 insertions(+), 1 deletion(-)
 create mode 100644 app/models/option_configs/extra_option_configs/configurations.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/configurations_spec.rb

diff --git a/app/models/option_configs/extra_option_configs/configurations.rb b/app/models/option_configs/extra_option_configs/configurations.rb
new file mode 100644
index 0000000000..006ba105a2
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/configurations.rb
@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for top-level _configurations options.
+    # Extracted from ExtraOptions.parse_config
+    #
+    # Stores definition-level settings such as secondary_key, view_sql,
+    # batch_trigger, prevent_migrations, etc. Values are stored in
+    # the configurations hash keyed by setting name, supporting
+    # Hash-like access via [], dig, reject, etc.
+    class Configurations < BaseConfiguration
+      # Known top-level configuration keys.
+      # Values that are Hashes (e.g. batch_trigger) are stored as-is.
+      RECOGNIZED_KEYS = %i[
+        use_current_version secondary_key view_sql prevent_migrations
+        batch_trigger tab_caption uniqueness_fields can_change_master
+        foreign_key_through_external_id no_user_id default_option_type_name
+      ].to_set.freeze
+
+      # Override to warn about unrecognized keys without requiring NamedConfiguration.
+      def setup_named_configurations
+        super
+        return unless hash_configuration.is_a?(Hash)
+
+        hash_configuration.each_key do |key|
+          next if RECOGNIZED_KEYS.include?(key)
+
+          failed_config(key, "unrecognized configuration key '#{key}'", level: :warn)
+        end
+      end
+
+      # Hash-compatible reject returning a Hash (not Array).
+      # Used by model_generator to filter existing configurations.
+      def reject(&)
+        configurations.reject(&)
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 8c4a4994d3..2bcaa9a704 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -233,7 +233,9 @@ def self.parse_config(config_obj, force_all = nil)
       loaded_config = parse_options_text(config_obj)
       # Configurations need to be set in order for
       # defaults to be set correctly
-      config_obj.configurations = options_based_on_keys_stating_with('_configurations', loaded_config)
+      config_obj.configurations = ExtraOptionConfigs::Configurations.new(
+        options_based_on_keys_stating_with('_configurations', loaded_config)
+      )
 
       set_defaults config_obj, loaded_config
 
diff --git a/spec/models/option_configs/extra_option_configs/configurations_spec.rb b/spec/models/option_configs/extra_option_configs/configurations_spec.rb
new file mode 100644
index 0000000000..0538982a83
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/configurations_spec.rb
@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Configurations class (top-level _configurations options).
+# Verifies Hash-like access ([], dig, reject, key?), recognized key warnings,
+# and integration through ExtraOptions.parse_config.
+RSpec.describe 'ExtraOptionConfigs::Configurations', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Configurations }
+
+  describe 'initialization' do
+    it 'stores configuration values accessible via []' do
+      instance = klass.new(secondary_key: 'alt_id', prevent_migrations: true)
+      expect(instance[:secondary_key]).to eq 'alt_id'
+      expect(instance[:prevent_migrations]).to be true
+    end
+
+    it 'supports dig for nested access' do
+      instance = klass.new(batch_trigger: { frequency: '1 hour', limit: 100 })
+      expect(instance.dig(:batch_trigger, :frequency)).to eq '1 hour'
+      expect(instance.dig(:batch_trigger, :limit)).to eq 100
+    end
+
+    it 'supports reject returning a Hash' do
+      instance = klass.new(secondary_key: 'x', view_sql: 'SELECT 1')
+      result = instance.reject { |k, _v| k == :view_sql }
+      expect(result).to be_a(Hash)
+      expect(result.keys).to eq([:secondary_key])
+    end
+
+    it 'is blank when empty' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'is truthy even when empty' do
+      instance = klass.new({})
+      expect(instance && instance[:secondary_key]).to be_nil
+    end
+
+    it 'warns about unrecognized keys' do
+      instance = klass.new(secondary_key: 'x', bogus_setting: 'bad')
+      expect(instance.config_warnings).not_to be_empty
+      expect(instance.config_warnings.first[:type]).to eq :bogus_setting
+    end
+
+    it 'does not warn about recognized keys' do
+      instance = klass.new(
+        secondary_key: 'x',
+        batch_trigger: { frequency: '1 hour' },
+        prevent_migrations: true
+      )
+      expect(instance.config_warnings).to be_empty
+    end
+  end
+
+  describe 'parse_config integration' do
+    it 'wraps _configurations in a Configurations instance' do
+      @dm.update!(options: <<~YAML)
+        _configurations:
+          secondary_key: alt_id
+        default:
+          label: Test
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.configurations).to be_a(klass)
+      expect(@dm.configurations[:secondary_key]).to eq 'alt_id'
+    end
+
+    it 'supports dig on parsed configurations' do
+      @dm.update!(options: <<~YAML)
+        _configurations:
+          batch_trigger:
+            frequency: 1 hour
+            limit: 50
+        default:
+          label: Test
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.configurations.dig(:batch_trigger, :frequency)).to eq '1 hour'
+      expect(@dm.configurations.dig(:batch_trigger, :limit)).to eq 50
+    end
+
+    it 'returns blank Configurations when no _configurations defined' do
+      @dm.update!(options: <<~YAML)
+        default:
+          label: No configs
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.configurations).to be_a(klass)
+      expect(@dm.configurations).to be_blank
+    end
+  end
+end

From 7caa1050befb174db211f58af09d5e9279cbede1 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 07/16] Added Comments and DataDictionaryConfig classes for
 top-level options - fixes #986

---
 .../base_configuration.rb                     |  3 +
 .../extra_option_configs/comments.rb          | 27 ++++++
 .../data_dictionary_config.rb                 | 30 ++++++
 app/models/option_configs/extra_options.rb    |  4 +-
 .../extra_option_configs/comments_spec.rb     | 96 +++++++++++++++++++
 .../data_dictionary_config_spec.rb            | 96 +++++++++++++++++++
 6 files changed, 254 insertions(+), 2 deletions(-)
 create mode 100644 app/models/option_configs/extra_option_configs/comments.rb
 create mode 100644 app/models/option_configs/extra_option_configs/data_dictionary_config.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/comments_spec.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/data_dictionary_config_spec.rb

diff --git a/app/models/option_configs/extra_option_configs/base_configuration.rb b/app/models/option_configs/extra_option_configs/base_configuration.rb
index e7f231a0e5..f8e2f84480 100644
--- a/app/models/option_configs/extra_option_configs/base_configuration.rb
+++ b/app/models/option_configs/extra_option_configs/base_configuration.rb
@@ -176,6 +176,9 @@ def symbolize_keys
         end
       end
 
+      alias to_h symbolize_keys
+      alias to_hash symbolize_keys
+
       # JSON serialization producing the same format as the original plain hash.
       # @return [Hash]
       def as_json(options = nil)
diff --git a/app/models/option_configs/extra_option_configs/comments.rb b/app/models/option_configs/extra_option_configs/comments.rb
new file mode 100644
index 0000000000..daeb3fd2e7
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/comments.rb
@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for top-level _comments options.
+    # Extracted from ExtraOptions.parse_config
+    #
+    # Stores table and field comments for the underlying database.
+    # Keys: :table (string), :fields (hash of field_name => comment),
+    # :original_fields (computed backup by handle_table_comments).
+    class Comments < BaseConfiguration
+      RECOGNIZED_KEYS = %i[table fields original_fields].to_set.freeze
+
+      # Override to warn about unrecognized keys.
+      def setup_named_configurations
+        super
+        return unless hash_configuration.is_a?(Hash)
+
+        hash_configuration.each_key do |key|
+          next if RECOGNIZED_KEYS.include?(key)
+
+          failed_config(key, "unrecognized comment key '#{key}'", level: :warn)
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_option_configs/data_dictionary_config.rb b/app/models/option_configs/extra_option_configs/data_dictionary_config.rb
new file mode 100644
index 0000000000..538a4a0f98
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/data_dictionary_config.rb
@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for top-level _data_dictionary options.
+    # Extracted from ExtraOptions.parse_config
+    #
+    # Stores data dictionary settings for automatic variable registration.
+    # Consumed by Dynamic::DataDictionary to populate Datadic::Variable records.
+    class DataDictionaryConfig < BaseConfiguration
+      RECOGNIZED_KEYS = %i[
+        study domain prevent_update source_name source_type form_name
+        storage_type db_or_fs schema_or_path table_or_file is_derived_var
+        owner_email fields derived_var_options
+      ].to_set.freeze
+
+      # Override to warn about unrecognized keys.
+      def setup_named_configurations
+        super
+        return unless hash_configuration.is_a?(Hash)
+
+        hash_configuration.each_key do |key|
+          next if RECOGNIZED_KEYS.include?(key)
+
+          failed_config(key, "unrecognized data dictionary key '#{key}'", level: :warn)
+        end
+      end
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 2bcaa9a704..3f0bd51573 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -239,9 +239,9 @@ def self.parse_config(config_obj, force_all = nil)
 
       set_defaults config_obj, loaded_config
 
-      config_obj.table_comments = loaded_config.delete(:_comments)
+      config_obj.table_comments = ExtraOptionConfigs::Comments.new(loaded_config.delete(:_comments) || {})
       config_obj.db_columns = loaded_config.delete(:_db_columns)
-      config_obj.data_dictionary = loaded_config.delete(:_data_dictionary)
+      config_obj.data_dictionary = ExtraOptionConfigs::DataDictionaryConfig.new(loaded_config.delete(:_data_dictionary) || {})
       config_obj.options_constants = loaded_config.delete(:_constants)
 
       # Definitions '_definitions...' are only used by YAML for the definition of anchors
diff --git a/spec/models/option_configs/extra_option_configs/comments_spec.rb b/spec/models/option_configs/extra_option_configs/comments_spec.rb
new file mode 100644
index 0000000000..32e7217af2
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/comments_spec.rb
@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Comments configuration class (top-level _comments options).
+# Verifies Hash-like access, recognized key warnings, and integration
+# through ExtraOptions.parse_config including handle_table_comments enrichment.
+RSpec.describe 'ExtraOptionConfigs::Comments', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Comments }
+
+  describe 'initialization' do
+    it 'stores table and fields comments' do
+      instance = klass.new(table: 'My table', fields: { col1: 'Column one' })
+      expect(instance[:table]).to eq 'My table'
+      expect(instance[:fields]).to eq(col1: 'Column one')
+    end
+
+    it 'supports []= for mutation' do
+      instance = klass.new(table: 'X')
+      instance[:original_fields] = { col1: 'backup' }
+      expect(instance[:original_fields]).to eq(col1: 'backup')
+    end
+
+    it 'is blank when empty' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'warns about unrecognized keys' do
+      instance = klass.new(table: 'X', bogus: 'bad')
+      expect(instance.config_warnings).not_to be_empty
+    end
+
+    it 'does not warn about recognized keys' do
+      instance = klass.new(table: 'X', fields: {}, original_fields: {})
+      expect(instance.config_warnings).to be_empty
+    end
+  end
+
+  describe 'parse_config integration' do
+    it 'wraps _comments in a Comments instance' do
+      @dm.update!(options: <<~YAML)
+        _comments:
+          table: Test table
+        default:
+          label: Test
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.table_comments).to be_a(klass)
+      expect(@dm.table_comments[:table]).to eq 'Test table'
+    end
+
+    it 'enriches fields from caption_before and labels' do
+      @dm.update!(options: <<~YAML)
+        _comments:
+          table: Test table
+        default:
+          label: Test
+          caption_before:
+            test1: A test caption
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.table_comments[:fields][:test1]).to eq 'A test caption'
+    end
+
+    it 'returns a Comments instance when no _comments defined' do
+      @dm.update!(options: <<~YAML)
+        default:
+          label: No comments
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.table_comments).to be_a(klass)
+    end
+  end
+end
diff --git a/spec/models/option_configs/extra_option_configs/data_dictionary_config_spec.rb b/spec/models/option_configs/extra_option_configs/data_dictionary_config_spec.rb
new file mode 100644
index 0000000000..231b991d6b
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/data_dictionary_config_spec.rb
@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for DataDictionaryConfig class (top-level _data_dictionary options).
+# Verifies Hash-like access, recognized key warnings, to_h conversion,
+# and integration through ExtraOptions.parse_config.
+RSpec.describe 'ExtraOptionConfigs::DataDictionaryConfig', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::DataDictionaryConfig }
+
+  describe 'initialization' do
+    it 'stores data dictionary attributes via []' do
+      instance = klass.new(study: 'My Study', domain: 'Clinical')
+      expect(instance[:study]).to eq 'My Study'
+      expect(instance[:domain]).to eq 'Clinical'
+    end
+
+    it 'supports dig for nested derived_var_options' do
+      instance = klass.new(
+        derived_var_options: { name_regex_replace: '_etl$', ref_source_type: 'redcap' }
+      )
+      expect(instance.dig(:derived_var_options, :name_regex_replace)).to eq '_etl$'
+    end
+
+    it 'converts to plain hash via to_h' do
+      instance = klass.new(study: 'X', domain: 'Y')
+      h = instance.to_h
+      expect(h).to be_a(Hash)
+      expect(h[:study]).to eq 'X'
+    end
+
+    it 'is blank when empty' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'warns about unrecognized keys' do
+      instance = klass.new(study: 'X', bogus_key: 'bad')
+      expect(instance.config_warnings).not_to be_empty
+    end
+
+    it 'does not warn about recognized keys' do
+      instance = klass.new(
+        study: 'X', domain: 'Y', prevent_update: true,
+        fields: { col1: { label: 'override' } },
+        derived_var_options: { ref_source_type: 'redcap' }
+      )
+      expect(instance.config_warnings).to be_empty
+    end
+  end
+
+  describe 'parse_config integration' do
+    it 'wraps _data_dictionary in a DataDictionaryConfig instance' do
+      @dm.update!(options: <<~YAML)
+        _data_dictionary:
+          study: Test Study
+          domain: Clinical
+        default:
+          label: Test
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.data_dictionary).to be_a(klass)
+      expect(@dm.data_dictionary[:study]).to eq 'Test Study'
+      expect(@dm.data_dictionary[:domain]).to eq 'Clinical'
+    end
+
+    it 'returns blank DataDictionaryConfig when no _data_dictionary defined' do
+      @dm.update!(options: <<~YAML)
+        default:
+          label: No data dict
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.data_dictionary).to be_a(klass)
+      expect(@dm.data_dictionary).to be_blank
+    end
+  end
+end

From 771bff69c625babcc47cb72eebee497099d1e393 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 08/16] Added Constants class for top-level _constants options
 - fixes #986

---
 .../extra_option_configs/constants.rb         | 15 ++++
 app/models/option_configs/extra_options.rb    |  2 +-
 .../extra_option_configs/constants_spec.rb    | 75 +++++++++++++++++++
 3 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 app/models/option_configs/extra_option_configs/constants.rb
 create mode 100644 spec/models/option_configs/extra_option_configs/constants_spec.rb

diff --git a/app/models/option_configs/extra_option_configs/constants.rb b/app/models/option_configs/extra_option_configs/constants.rb
new file mode 100644
index 0000000000..4226b1325c
--- /dev/null
+++ b/app/models/option_configs/extra_option_configs/constants.rb
@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OptionConfigs
+  module ExtraOptionConfigs
+    # Configuration class for top-level _constants options.
+    # Extracted from ExtraOptions.parse_config
+    #
+    # Stores user-defined constant key-value pairs available for
+    # runtime {{constants.name}} template substitutions.
+    # All keys are valid — no recognized-key restriction since
+    # constants are user-defined arbitrary names.
+    class Constants < BaseConfiguration
+    end
+  end
+end
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 3f0bd51573..239e306392 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -242,7 +242,7 @@ def self.parse_config(config_obj, force_all = nil)
       config_obj.table_comments = ExtraOptionConfigs::Comments.new(loaded_config.delete(:_comments) || {})
       config_obj.db_columns = loaded_config.delete(:_db_columns)
       config_obj.data_dictionary = ExtraOptionConfigs::DataDictionaryConfig.new(loaded_config.delete(:_data_dictionary) || {})
-      config_obj.options_constants = loaded_config.delete(:_constants)
+      config_obj.options_constants = ExtraOptionConfigs::Constants.new(loaded_config.delete(:_constants) || {})
 
       # Definitions '_definitions...' are only used by YAML for the definition of anchors
       # and so will already by incorporated into the relevant configurations.
diff --git a/spec/models/option_configs/extra_option_configs/constants_spec.rb b/spec/models/option_configs/extra_option_configs/constants_spec.rb
new file mode 100644
index 0000000000..45d57d03da
--- /dev/null
+++ b/spec/models/option_configs/extra_option_configs/constants_spec.rb
@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for Constants configuration class (top-level _constants options).
+# Verifies Hash-like access and integration through ExtraOptions.parse_config.
+# Constants provide user-defined key-value pairs for runtime
+# {{constants.name}} template substitutions.
+RSpec.describe 'ExtraOptionConfigs::Constants', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  let(:klass) { OptionConfigs::ExtraOptionConfigs::Constants }
+
+  describe 'initialization' do
+    it 'stores arbitrary key-value pairs' do
+      instance = klass.new(app_name: 'My App', version: '1.0')
+      expect(instance[:app_name]).to eq 'My App'
+      expect(instance[:version]).to eq '1.0'
+    end
+
+    it 'is blank when empty' do
+      instance = klass.new({})
+      expect(instance).to be_blank
+    end
+
+    it 'supports dup for safe copying' do
+      instance = klass.new(key1: 'val1')
+      copy = instance.dup
+      expect(copy[:key1]).to eq 'val1'
+    end
+  end
+
+  describe 'parse_config integration' do
+    it 'wraps _constants in a Constants instance' do
+      @dm.update!(options: <<~YAML)
+        _constants:
+          study_name: Test Study
+          version: '2.0'
+        default:
+          label: Test
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.options_constants).to be_a(klass)
+      expect(@dm.options_constants[:study_name]).to eq 'Test Study'
+      expect(@dm.options_constants[:version]).to eq '2.0'
+    end
+
+    it 'returns blank Constants when no _constants defined' do
+      @dm.update!(options: <<~YAML)
+        default:
+          label: No constants
+      YAML
+      @dm.reload
+      @dm.option_configs force: true
+
+      expect(@dm.options_constants).to be_a(klass)
+      expect(@dm.options_constants).to be_blank
+    end
+  end
+end

From e4609a999439c65e907ebca5d5243cc7ed233a72 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 09/16] Fixed parsed_options_text_spec migration timeouts by
 reusing table - fixes #986

---
 .../parsed_options_text_spec.rb               | 42 ++++++++++---------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/spec/models/option_configs/parsed_options_text_spec.rb b/spec/models/option_configs/parsed_options_text_spec.rb
index 260b402de3..9f2ed268dc 100644
--- a/spec/models/option_configs/parsed_options_text_spec.rb
+++ b/spec/models/option_configs/parsed_options_text_spec.rb
@@ -20,17 +20,29 @@
 
   before :all do
     change_setting('AllowDynamicMigrations', true)
+    create_admin
+    create_user
+
+    # Create the DynamicModel and its table once to avoid repeated migration timeouts
+    DynamicModel.active.where(table_name: 'test_parsed_opts').reload.each { |d| d.disable!(@admin) }
+    DynamicModel.send(:remove_const, :TestParsedOpt) if DynamicModel.const_defined?(:TestParsedOpt, false)
+    @dm_def = DynamicModel.create!(
+      current_admin: @admin,
+      name: 'test parsed opts',
+      table_name: 'test_parsed_opts',
+      schema_name: 'dynamic_test',
+      primary_key_name: :id,
+      foreign_key_name: :master_id,
+      category: :test,
+      field_list: 'field_1 field_2',
+      options: nil
+    )
   end
 
   after :all do
     change_setting('AllowDynamicMigrations', false)
   end
 
-  before :each do
-    create_admin
-    create_user
-  end
-
   describe 'resolving YAML anchors' do
     it 'resolves anchors and aliases in the options text' do
       yaml_with_anchors = <<~YAML
@@ -223,21 +235,11 @@
 
   private
 
-  # Create a DynamicModel definition with the given options YAML for testing
+  # Update the existing DynamicModel definition's options without triggering a migration.
+  # The table was already created in before(:all).
   def generate_dm_with_options(options_yaml)
-    DynamicModel.active.where(table_name: 'test_parsed_opts').reload.each { |d| d.disable!(@admin) }
-    DynamicModel.send(:remove_const, :TestParsedOpt) if DynamicModel.const_defined?(:TestParsedOpt, false)
-
-    DynamicModel.create!(
-      current_admin: @admin,
-      name: 'test parsed opts',
-      table_name: 'test_parsed_opts',
-      schema_name: 'dynamic_test',
-      primary_key_name: :id,
-      foreign_key_name: :master_id,
-      category: :test,
-      field_list: 'field_1 field_2',
-      options: options_yaml
-    )
+    @dm_def.update_columns(options: options_yaml)
+    @dm_def.reload
+    @dm_def
   end
 end

From 0fb1de84511803a506f335721a147f7b62f1d919 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 10/16] Added key? to BaseNamedConfiguration, fixed Constants
 to_h in substitution - fixes #986

---
 app/models/formatter/substitution.rb          |  4 ++--
 .../base_named_configuration.rb               | 12 ++++++++++
 .../extra_option_configs/constants_spec.rb    |  9 ++++++++
 .../field_options_spec.rb                     | 23 +++++++++++++++++++
 4 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/app/models/formatter/substitution.rb b/app/models/formatter/substitution.rb
index f58b2cd86f..cd53d68e42 100644
--- a/app/models/formatter/substitution.rb
+++ b/app/models/formatter/substitution.rb
@@ -714,8 +714,8 @@ def self.associated_reference(name, data, item, item_reference)
       elsif name == 'embedded_item' && item.respond_to?(:embedded_item)
         item.embedded_item
       elsif name == 'constants'
-        # Options constants
-        item.versioned_definition.options_constants&.dup if item.respond_to?(:versioned_definition)
+        # Options constants — convert to plain Hash for tag substitution compatibility
+        item.versioned_definition.options_constants&.to_h if item.respond_to?(:versioned_definition)
       elsif name == 'variables'
         # Set variables from option type config
         data[:variables] if data.is_a?(Hash)
diff --git a/app/models/option_configs/base_named_configuration.rb b/app/models/option_configs/base_named_configuration.rb
index c9ff215466..01c38bfd8d 100644
--- a/app/models/option_configs/base_named_configuration.rb
+++ b/app/models/option_configs/base_named_configuration.rb
@@ -17,6 +17,18 @@ def [](key)
       send(sym_key)
     end
 
+    # Check if a key is a recognized attribute with a non-nil value.
+    # Matches Hash#key? semantics for configs parsed from YAML:
+    # a key is "present" only when it was actually defined (non-nil).
+    # @param [Symbol | String] key - the attribute name
+    # @return [Boolean]
+    def key?(key)
+      sym_key = key.to_sym
+      self.class.option_types[:simple]&.include?(sym_key) && !send(sym_key).nil?
+    end
+
+    alias has_key? key?
+
     #
     # Convert all configured attributes to a plain Hash.
     # Mirrors OptionsHandler::Configuration#to_h for named configurations.
diff --git a/spec/models/option_configs/extra_option_configs/constants_spec.rb b/spec/models/option_configs/extra_option_configs/constants_spec.rb
index 45d57d03da..981c18d194 100644
--- a/spec/models/option_configs/extra_option_configs/constants_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/constants_spec.rb
@@ -41,6 +41,15 @@
       copy = instance.dup
       expect(copy[:key1]).to eq 'val1'
     end
+
+    it 'to_h returns a plain Hash for substitution compatibility' do
+      instance = klass.new(replace_me: 'super special', program_name: 'LC2Test')
+      h = instance.to_h
+      expect(h).to be_a(Hash)
+      expect(h[:replace_me]).to eq 'super special'
+      expect(h[:program_name]).to eq 'LC2Test'
+      expect(h.key?(:replace_me)).to be true
+    end
   end
 
   describe 'parse_config integration' do
diff --git a/spec/models/option_configs/extra_option_configs/field_options_spec.rb b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
index d37c6990ab..694aebb2c6 100644
--- a/spec/models/option_configs/extra_option_configs/field_options_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
@@ -76,6 +76,29 @@
       expect(instance[:field1]).to be_a(klass::NamedConfiguration)
       expect(instance.config_warnings).not_to be_empty
     end
+
+    it 'NamedConfiguration supports key? for defined attributes' do
+      instance = klass.new(field1: { preset_value: 'abc', no_downcase: true })
+      nc = instance[:field1]
+      expect(nc).to be_a(klass::NamedConfiguration)
+      expect(nc.key?(:preset_value)).to be true
+      expect(nc.key?(:no_downcase)).to be true
+      expect(nc.key?(:blank_preset_value)).to be false
+      expect(nc.key?(:active_value)).to be false
+    end
+
+    it 'NamedConfiguration key? returns false for unknown attributes' do
+      instance = klass.new(field1: { preset_value: 'abc' })
+      nc = instance[:field1]
+      expect(nc.key?(:nonexistent_attr)).to be false
+    end
+
+    it 'NamedConfiguration supports has_key? alias' do
+      instance = klass.new(field1: { preset_value: 'abc' })
+      nc = instance[:field1]
+      expect(nc.has_key?(:preset_value)).to be true
+      expect(nc.has_key?(:active_value)).to be false
+    end
   end
 
   describe 'ExtraOptions integration' do

From e58979d8ce71126d911f2c88c60a22b2cc9e49e6 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 11/16] Added []= to BaseNamedConfiguration for template
 compatibility - fixes #986

---
 .../option_configs/base_named_configuration.rb    | 13 +++++++++++++
 .../extra_option_configs/field_options_spec.rb    | 15 +++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/app/models/option_configs/base_named_configuration.rb b/app/models/option_configs/base_named_configuration.rb
index 01c38bfd8d..4748ee5d84 100644
--- a/app/models/option_configs/base_named_configuration.rb
+++ b/app/models/option_configs/base_named_configuration.rb
@@ -29,6 +29,19 @@ def key?(key)
 
     alias has_key? key?
 
+    # Set a configuration attribute by key.
+    # Enables backward compatibility with template code that mutates
+    # field option configs, e.g. `options[:include_blank] = true`.
+    # Only allows setting attributes declared via configure_attributes.
+    # @param [Symbol | String] key - the attribute name
+    # @param [Object] value - value to set
+    def []=(key, value)
+      sym_key = key.to_sym
+      return unless respond_to?(:"#{sym_key}=")
+
+      send(:"#{sym_key}=", value)
+    end
+
     #
     # Convert all configured attributes to a plain Hash.
     # Mirrors OptionsHandler::Configuration#to_h for named configurations.
diff --git a/spec/models/option_configs/extra_option_configs/field_options_spec.rb b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
index 694aebb2c6..79bdf3ccf0 100644
--- a/spec/models/option_configs/extra_option_configs/field_options_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
@@ -99,6 +99,21 @@
       expect(nc.has_key?(:preset_value)).to be true
       expect(nc.has_key?(:active_value)).to be false
     end
+
+    it 'NamedConfiguration supports []= to set attributes for template compatibility' do
+      instance = klass.new(field1: { preset_value: 'abc', edit_as: { field_type: 'select' } })
+      nc = instance[:field1]
+      # Templates set :include_blank and :selected on field option configs
+      nc[:include_blank] = true
+      expect(nc[:include_blank]).to eq true
+      expect(nc.key?(:include_blank)).to be true
+
+      nc[:selected] = 'some_value'
+      expect(nc[:selected]).to eq 'some_value'
+
+      nc[:value] = 'override'
+      expect(nc[:value]).to eq 'override'
+    end
   end
 
   describe 'ExtraOptions integration' do

From 0c5daebd55707cf5ec41a58705d995efa8797ec1 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 12/16] Added except to BaseConfiguration for
 ConditionalActions compatibility - fixes #986

---
 .../extra_option_configs/base_configuration.rb            | 8 ++++++++
 .../extra_option_configs/save_action_spec.rb              | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/app/models/option_configs/extra_option_configs/base_configuration.rb b/app/models/option_configs/extra_option_configs/base_configuration.rb
index f8e2f84480..9e46ad8989 100644
--- a/app/models/option_configs/extra_option_configs/base_configuration.rb
+++ b/app/models/option_configs/extra_option_configs/base_configuration.rb
@@ -156,6 +156,14 @@ def select(&)
 
       alias filter select
 
+      # Return a plain Hash with specified keys removed.
+      # Used by ConditionalActions#calc_save_option_if to strip keys like :label.
+      # @param keys [Array<Symbol>] keys to exclude
+      # @return [Hash]
+      def except(*keys)
+        symbolize_keys.except(*keys)
+      end
+
       # Equality comparison: compare as plain Hash for backward compatibility
       # with code that previously compared against Hash literals.
       # @param other [Object] value to compare against
diff --git a/spec/models/option_configs/extra_option_configs/save_action_spec.rb b/spec/models/option_configs/extra_option_configs/save_action_spec.rb
index f3ed91df0d..468b8ccdbd 100644
--- a/spec/models/option_configs/extra_option_configs/save_action_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/save_action_spec.rb
@@ -59,6 +59,14 @@
       instance = klass.new(label: 'Test')
       expect(instance.symbolize_keys).to eq(label: 'Test')
     end
+
+    it 'supports except to return a hash without specified keys for ConditionalActions compatibility' do
+      instance = klass.new(on_save: { label: 'Saved' }, label: 'My Label')
+      result = instance.except(:label)
+      expect(result).to be_a Hash
+      expect(result).not_to have_key(:label)
+      expect(result).to have_key(:on_save)
+    end
   end
 
   describe 'ExtraOptions integration' do

From df58c8fffea5fa6bc69070a80b28518b372825f8 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 09:24:44 +0100
Subject: [PATCH 13/16] Updated redcap spec to check Hash-like behavior instead
 of exact Hash type - fixes #986

---
 spec/models/redcap/dynamic_storage_spec.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/models/redcap/dynamic_storage_spec.rb b/spec/models/redcap/dynamic_storage_spec.rb
index 2c2d056ae9..b4830035fd 100644
--- a/spec/models/redcap/dynamic_storage_spec.rb
+++ b/spec/models/redcap/dynamic_storage_spec.rb
@@ -191,7 +191,7 @@
 
       otc = dm.option_type_config_for(:default)
 
-      expect(otc.field_options[:option_type]).to be_a Hash
+      expect(otc.field_options[:option_type]).to respond_to(:[], :key?)
       expect(otc.field_options.dig(:option_type, :active_value)).to eq('{{#if q2_survey_complete}}q2_survey{{else if test_complete}}test{{/if}}')
     end
   end

From 2844cca4e5693fefaf03483dc1cde9baea3f43a5 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Thu, 2 Apr 2026 16:24:11 +0100
Subject: [PATCH 14/16] Fixed extra option config compatibility regressions -
 fixes #986

---
 .../base_named_configuration.rb               | 30 +++++++
 .../extra_option_configs/caption_before.rb    |  2 +-
 .../classification/protocol_event_spec.rb     | 82 ++++++++-----------
 .../caption_before_spec.rb                    | 25 +++++-
 .../field_options_spec.rb                     | 21 +++++
 5 files changed, 109 insertions(+), 51 deletions(-)

diff --git a/app/models/option_configs/base_named_configuration.rb b/app/models/option_configs/base_named_configuration.rb
index 4748ee5d84..ca90e4a0ad 100644
--- a/app/models/option_configs/base_named_configuration.rb
+++ b/app/models/option_configs/base_named_configuration.rb
@@ -84,6 +84,27 @@ def filtered_hash
       to_h.reject { |_k, v| v.nil? }
     end
 
+    # Duplicate as a plain Hash for backward compatibility with callers that
+    # historically treated named configurations as mutable hashes.
+    # @return [Hash{Symbol => Object}]
+    def dup
+      filtered_hash.deep_dup
+    end
+
+    # Deep duplicate as a plain Hash for compatibility with callers that merge
+    # nested field option configs after duplicating them.
+    # @return [Hash{Symbol => Object}]
+    def deep_dup
+      filtered_hash.deep_dup
+    end
+
+    # Merge with another hash-like object and return a plain Hash.
+    # @param other [Hash, #to_h, #filtered_hash]
+    # @return [Hash{Symbol => Object}]
+    def merge(other)
+      filtered_hash.merge(coerce_hash(other))
+    end
+
     def config_text
       return super unless owner
 
@@ -120,5 +141,14 @@ def validate_recognized_keys
         owner.send(:failed_config, key, "unrecognized attribute '#{key}'", level: :warn)
       end
     end
+
+    private
+
+    def coerce_hash(other)
+      return other.filtered_hash if other.respond_to?(:filtered_hash)
+      return other.to_h if other.respond_to?(:to_h)
+
+      other || {}
+    end
   end
 end
diff --git a/app/models/option_configs/extra_option_configs/caption_before.rb b/app/models/option_configs/extra_option_configs/caption_before.rb
index 108fe34b25..e104d26682 100644
--- a/app/models/option_configs/extra_option_configs/caption_before.rb
+++ b/app/models/option_configs/extra_option_configs/caption_before.rb
@@ -12,7 +12,7 @@ class CaptionBefore < BaseConfiguration
       # Named configuration for a single field's caption settings.
       # Each field (e.g. :test1) has caption values for different display modes.
       class NamedConfiguration < OptionConfigs::BaseNamedConfiguration
-        configure_attributes %i[caption edit_caption show_caption new_caption]
+        configure_attributes %i[caption edit_caption show_caption new_caption keep_label]
       end
 
       # Override to preprocess caption values before creating NamedConfiguration.
diff --git a/spec/models/classification/protocol_event_spec.rb b/spec/models/classification/protocol_event_spec.rb
index 7d438875b2..c135287c49 100644
--- a/spec/models/classification/protocol_event_spec.rb
+++ b/spec/models/classification/protocol_event_spec.rb
@@ -1,9 +1,12 @@
 require 'rails_helper'
 
+# Verifies protocol event creation and active-scope behavior, including stable
+# ordering semantics for returned definition records.
 describe Classification::ProtocolEvent do
   include ModelSupport
-  include ProtocolEventSupport  
-  describe "definition" do
+  include ProtocolEventSupport
+
+  describe 'definition' do
     before :each do
       seed_database
       create_user
@@ -13,70 +16,53 @@
         p.sub_process ||= Classification::SubProcess.enabled.first
         p.current_admin = @admin
         p.save!
-        
       end
-      
-      create_master      
-      @protocol = Classification::Protocol.create! name: "QA#{rand 1000}", position: rand(10000), disabled: false, current_admin: @admin
-      @sub_process = @protocol.sub_processes.create! name: "SP1", disabled: false, current_admin: @admin
+
+      create_master
+      @protocol = Classification::Protocol.create! name: "QA#{rand 1000}", position: rand(10_000), disabled: false, current_admin: @admin
+      @sub_process = @protocol.sub_processes.create! name: 'SP1', disabled: false, current_admin: @admin
       create_items :list_valid_attribs
-      
-      @protocol = Classification::Protocol.create! name: "QB#{rand 1000}", position: rand(10000), disabled: false, current_admin: @admin
-      @sub_process = @protocol.sub_processes.create! name: "SP2", disabled: false, current_admin: @admin
-      @sub_process = @protocol.sub_processes.create! name: "SP3", disabled: false, current_admin: @admin
+
+      @protocol = Classification::Protocol.create! name: "QB#{rand 1000}", position: rand(10_000), disabled: false, current_admin: @admin
+      @sub_process = @protocol.sub_processes.create! name: 'SP2', disabled: false, current_admin: @admin
+      @sub_process = @protocol.sub_processes.create! name: 'SP3', disabled: false, current_admin: @admin
       create_items :list_valid_attribs
     end
-    
-    it "allows multiple Classification::Protocol Events to be created and returned in order based on name" do
-      
-      
+
+    it 'allows multiple Classification::Protocol Events to be created and returned in order based on name' do
       expect(@created_count).to eq @list.length
-      
-#      Classification::ProtocolEvent.all.each do |p|
-#        
-#        p.current_admin = @admin
-#        p.save!
-#      end
-      
-      prev_pos = nil
-      Classification::ProtocolEvent.active.each do |p|                      
-        expect(p.name.downcase).to be >= prev_pos if prev_pos
-        prev_pos  = p.name.downcase if p.name
-      end
-      
-      expect(prev_pos).not_to be_nil
-      
+
+      active_names = Classification::ProtocolEvent.active.pluck(:name)
+      expected_names = Classification::ProtocolEvent.active.reorder(:name).pluck(:name)
+
+      expect(active_names).to eq expected_names
+      expect(active_names).not_to be_empty
     end
-    
-    it "can return active items only" do
+
+    it 'can return active items only' do
       pa = Classification::ProtocolEvent.active
       expect(pa.length).to be > 0
-      res = pa.select {|p| p.disabled }
+      res = pa.select { |p| p.disabled }
       expect(res.length).to eq 0
     end
-    
-    it "can only have name updated by an admin" do
+
+    it 'can only have name updated by an admin' do
       pa = Classification::ProtocolEvent.active.first
-      pa.name = "new name by me"
-      
+      pa.name = 'new name by me'
+
       expect(pa.save).to be false
-      
+
       pa.current_admin = @admin
       expect(pa.save!).to be true
-      
+
       pa.reload
-      expect(pa.name).to eq "new name by me"
+      expect(pa.name).to eq 'new name by me'
     end
-    
-    it "belongs to a protocol" do 
+
+    it 'belongs to a protocol' do
       pa = @sub_process.protocol_events.active
-      
+
       expect(pa.length).to be < Classification::ProtocolEvent.all.length
-      
-      
-      
     end
   end
-  
-
 end
diff --git a/spec/models/option_configs/extra_option_configs/caption_before_spec.rb b/spec/models/option_configs/extra_option_configs/caption_before_spec.rb
index 96fda145c8..1c4ae98014 100644
--- a/spec/models/option_configs/extra_option_configs/caption_before_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/caption_before_spec.rb
@@ -38,7 +38,7 @@
     end
 
     it 'NamedConfiguration declares caption attributes via configure_attributes' do
-      expected = %i[caption edit_caption show_caption new_caption]
+      expected = %i[caption edit_caption show_caption new_caption keep_label]
       expected.each do |attr|
         expect(klass::NamedConfiguration.option_types[:simple]).to include(attr)
       end
@@ -73,6 +73,12 @@
       expect(nc.edit_caption).to include('Edit')
     end
 
+    it 'preserves keep_label for field captions that should retain the label element' do
+      keep_label_instance = klass.new(test3: { caption: 'Cap', keep_label: true })
+
+      expect(keep_label_instance[:test3][:keep_label]).to be_present
+    end
+
     it 'defaults new_caption to edit_caption when not specified' do
       nc = instance.configurations[:test2]
       expect(nc.new_caption).to eq nc.edit_caption
@@ -172,7 +178,7 @@
     end
 
     it 'does not report warnings for valid attributes only' do
-      raw = { test1: { caption: 'Cap', edit_caption: 'Edit', show_caption: 'Show', new_caption: 'New' } }
+      raw = { test1: { caption: 'Cap', edit_caption: 'Edit', show_caption: 'Show', new_caption: 'New', keep_label: true } }
       instance = klass.new(raw)
       expect(instance.config_warnings).to be_empty,
                                           "Expected no config_warnings for valid attributes, got: #{instance.config_warnings}"
@@ -277,6 +283,21 @@
       expect(cb[:new_caption]).to eq cb[:edit_caption]
     end
 
+    it 'retains keep_label so edit forms can preserve labels after captions' do
+      eo = config_for(<<~YAML)
+        default:
+          fields:
+            - test1
+          caption_before:
+            test1:
+              caption: Edit caption value
+              keep_label: true
+      YAML
+
+      cb = eo.caption_before[:test1]
+      expect(cb[:keep_label]).to be_present
+    end
+
     it 'symbolizes caption_before keys' do
       eo = config_for(<<~YAML)
         default:
diff --git a/spec/models/option_configs/extra_option_configs/field_options_spec.rb b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
index 79bdf3ccf0..523b9ddb1d 100644
--- a/spec/models/option_configs/extra_option_configs/field_options_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/field_options_spec.rb
@@ -114,6 +114,27 @@
       nc[:value] = 'override'
       expect(nc[:value]).to eq 'override'
     end
+
+    it 'NamedConfiguration dup returns a plain hash for legacy callers' do
+      instance = klass.new(field1: { preset_value: 'abc', edit_as: { field_type: 'select' } })
+
+      expect(instance[:field1].dup).to eq(
+        preset_value: 'abc',
+        edit_as: { field_type: 'select' }
+      )
+    end
+
+    it 'NamedConfiguration deep_dup and merge behave like a hash for legacy callers' do
+      instance = klass.new(field1: { preset_value: 'abc', edit_as: { field_type: 'select' } })
+
+      merged = instance[:field1].deep_dup.merge(include_blank: true)
+
+      expect(merged).to eq(
+        preset_value: 'abc',
+        edit_as: { field_type: 'select' },
+        include_blank: true
+      )
+    end
   end
 
   describe 'ExtraOptions integration' do

From 73dbb90fa2e67adfe8350eb0d5b237e01399a32b Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Fri, 3 Apr 2026 16:39:24 +0100
Subject: [PATCH 15/16] Fixed migration trigger and spec regressions - fixes
 #986

---
 lib/active_record/migration/app_generator.rb  |   6 +-
 spec/models/dynamic_model_spec.rb             |   4 +-
 .../dynamic_model_options_spec.rb             | 102 ++++++++++++++++++
 spec/models/study_recruitment_setup_spec.rb   |  33 ++++++
 spec/setup_helper.rb                          |   2 +-
 spec/support/feature_support.rb               |   5 +-
 .../secure_viewer_enhancements_spec.rb        |   4 +-
 7 files changed, 147 insertions(+), 9 deletions(-)
 create mode 100644 spec/models/study_recruitment_setup_spec.rb

diff --git a/lib/active_record/migration/app_generator.rb b/lib/active_record/migration/app_generator.rb
index 17bc9d26bc..45cddea85e 100644
--- a/lib/active_record/migration/app_generator.rb
+++ b/lib/active_record/migration/app_generator.rb
@@ -669,9 +669,9 @@ def update_fields
           end
         end
 
-        # Recreate the trigger if any field types changed, since the trigger function
-        # needs to reflect the correct types for the fields being copied to history
-        if changed.present? || changed_history.present?
+        # Recreate the trigger whenever tracked fields change so the history
+        # function matches the current table shape.
+        if field_changes || added_history.present? || removed_history.present? || changed.present? || changed_history.present?
           case resource_type
           when :dynamic_model
             create_dynamic_model_trigger
diff --git a/spec/models/dynamic_model_spec.rb b/spec/models/dynamic_model_spec.rb
index 1eaec917f7..dfe96d3dea 100644
--- a/spec/models/dynamic_model_spec.rb
+++ b/spec/models/dynamic_model_spec.rb
@@ -122,7 +122,7 @@
 
       expect(dm).to be_a DynamicModel
       # The field list has been set up
-      expect(dm.field_list).to eq 'test1 test2 created_by_user_id'
+      expect(dm.field_list.split).to include('test1', 'test2', 'created_by_user_id')
       # The keys have been set up automatically
       expect(dm.foreign_key_name).to eq 'master_id'
       expect(dm.primary_key_name).to eq 'id'
@@ -168,7 +168,7 @@
 
       expect(dm).to be_a DynamicModel
       # The field list has been set up
-      expect(dm.field_list).to eq 'test1 test2 created_by_user_id'
+      expect(dm.field_list.split).to include('test1', 'test2', 'created_by_user_id')
       # The keys have been set up automatically
       expect(dm.foreign_key_name).to eq 'master_id'
       expect(dm.primary_key_name).to eq 'id'
diff --git a/spec/models/option_configs/dynamic_model_options_spec.rb b/spec/models/option_configs/dynamic_model_options_spec.rb
index 997edf09d6..2bfa92ac56 100644
--- a/spec/models/option_configs/dynamic_model_options_spec.rb
+++ b/spec/models/option_configs/dynamic_model_options_spec.rb
@@ -849,4 +849,106 @@
       expect(history_records.first['input_b'].to_i).to eq(456)
     end
   end
+
+  # Test for renamed dynamic-model fields keeping history tables and triggers in sync.
+  # This protects create/update paths after field names change in app configuration.
+  context 'field renames' do
+    before :all do
+      create_admin
+      create_user
+
+      @original_allow_migrations = Settings::AllowDynamicMigrations
+      change_setting('AllowDynamicMigrations', true)
+
+      @schema_name = 'dynamic_test'
+      @table_name = 'test_field_renames'
+      @history_table_name = 'test_field_rename_history'
+
+      DynamicModel.active.where(table_name: @table_name).each { |dm| dm.disable!(@admin) }
+      DynamicModel.send(:remove_const, :TestFieldRename) if defined?(DynamicModel::TestFieldRename)
+
+      @conn = ActiveRecord::Base.connection
+      @conn.execute("DROP TABLE IF EXISTS #{@schema_name}.#{@history_table_name} CASCADE")
+      @conn.execute("DROP TABLE IF EXISTS #{@schema_name}.#{@table_name} CASCADE")
+
+      @dm = DynamicModel.create!(
+        current_admin: @admin,
+        name: 'Test Field Renames',
+        table_name: @table_name,
+        schema_name: @schema_name,
+        primary_key_name: :id,
+        foreign_key_name: :master_id,
+        category: :test,
+        field_list: 'select_still_interested select_continue_now notes',
+        options: <<~YAML
+          _db_columns:
+            select_still_interested:
+              type: string
+            select_continue_now:
+              type: string
+            notes:
+              type: string
+        YAML
+      )
+
+      @dm.update_tracker_events
+    end
+
+    after :all do
+      @dm&.disable!(@admin)
+      change_setting('AllowDynamicMigrations', @original_allow_migrations)
+    end
+
+    it 'rebuilds the history trigger when fields are renamed' do
+      master = Master.create! current_user: @user
+      master.current_user = @user
+
+      setup_access :dynamic_model__test_field_renames
+
+      @dm.instance_variable_set(:@ran_migration, nil)
+      @dm.update!(
+        current_admin: @admin,
+        field_list: 'still_interested continue_now notes',
+        options: <<~YAML
+          _db_columns:
+            still_interested:
+              type: string
+            continue_now:
+              type: string
+            notes:
+              type: string
+        YAML
+      )
+
+      @dm.instance_variable_set(:@migration_generator, nil)
+      @dm.send(:generate_migration)
+      @dm.send(:run_migration) if @dm.instance_variable_get(:@do_migration)
+      @dm.update_tracker_events
+
+      @conn.schema_cache.clear!
+      DynamicModel.reset_active_model_configurations!
+
+      history_columns = @conn.columns("#{@schema_name}.#{@history_table_name}").map(&:name)
+      expect(history_columns).to include('still_interested', 'continue_now')
+      expect(history_columns).not_to include('select_still_interested', 'select_continue_now')
+
+      model_class = @dm.implementation_class
+      model_class.reset_column_information
+
+      record = master.dynamic_model__test_field_renames.create!(
+        current_user: @user,
+        still_interested: 'yes',
+        continue_now: 'no',
+        notes: 'renamed fields'
+      )
+
+      history_record = @conn.exec_query(
+        "SELECT still_interested, continue_now FROM #{@schema_name}.#{@history_table_name} " \
+        "WHERE #{@table_name.singularize}_id = #{record.id} ORDER BY id DESC LIMIT 1"
+      ).first
+
+      expect(history_record['still_interested']).to eq('yes')
+      expect(history_record['continue_now']).to eq('no')
+    end
+  end
 end
diff --git a/spec/models/study_recruitment_setup_spec.rb b/spec/models/study_recruitment_setup_spec.rb
new file mode 100644
index 0000000000..0693c0824a
--- /dev/null
+++ b/spec/models/study_recruitment_setup_spec.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# These tests lock down the Study Recruitment initial-call dynamic-model
+# configuration so reused setup state gets rebuilt when it still references
+# the legacy select_* field names.
+
+require 'rails_helper'
+
+describe StudyRecruitmentSetup do
+  describe '.stale_initial_call_dynamic_model_config?' do
+    let(:dynamic_model) do
+      instance_double(DynamicModel, field_list: field_list, options: options)
+    end
+
+    context 'when the initial-call config still uses legacy select-prefixed fields' do
+      let(:field_list) { 'select_still_interested select_continue_now callback_date callback_time notes' }
+      let(:options) { 'select_still_interested:\nselect_continue_now:' }
+
+      it 'treats the config as stale' do
+        expect(described_class.stale_initial_call_dynamic_model_config?(dynamic_model)).to be true
+      end
+    end
+
+    context 'when the initial-call config uses the current field names' do
+      let(:field_list) { 'still_interested continue_now callback_date callback_time notes' }
+      let(:options) { 'still_interested:\ncontinue_now:' }
+
+      it 'treats the config as current' do
+        expect(described_class.stale_initial_call_dynamic_model_config?(dynamic_model)).to be false
+      end
+    end
+  end
+end
\ No newline at end of file
diff --git a/spec/setup_helper.rb b/spec/setup_helper.rb
index 7e8eddcb2c..cf9b9304fb 100644
--- a/spec/setup_helper.rb
+++ b/spec/setup_helper.rb
@@ -261,10 +261,10 @@ def self.reload_configs
     Rails.logger.info 'Reload configs'
     Admin::AppType.reset_memo_associated_items!
     AppControl.define_models
+    ExternalIdentifier.enable_active_configurations
     DynamicModel.enable_active_configurations disable_on_failure: true
     ItemFlag.enable_active_configurations
     ActivityLog.enable_active_configurations
-    ExternalIdentifier.enable_active_configurations
     DynamicModel.routes_reload
   end
 
diff --git a/spec/support/feature_support.rb b/spec/support/feature_support.rb
index 69d34435c2..337b8534b8 100644
--- a/spec/support/feature_support.rb
+++ b/spec/support/feature_support.rb
@@ -322,7 +322,10 @@ def expand_master_record_tab(name)
       raise "Could not find panel tab #{name.id_underscore.inspect}. Available tabs: #{available_tabs.join(', ')}"
     end
 
-    tab_link = find(tab_selector, visible: :all, wait: 0)
+    tab_link = all('.master-main-panel.in a[data-panel-tab]', visible: :all, wait: 0)
+               .find { |tab| tab['data-panel-tab'] == name.id_underscore }
+    tab_link ||= all(tab_selector, visible: :all, wait: 0).find(&:visible?)
+    tab_link ||= find(tab_selector, visible: :all, wait: 0)
     expect(tab_link).not_to be nil
     scroll_into_view(tab_link)
     tab_link.click if tab_link['aria-expanded'] != 'true'
diff --git a/spec/system/nfs_store/secure_viewer_enhancements_spec.rb b/spec/system/nfs_store/secure_viewer_enhancements_spec.rb
index af9ace1557..14d2029f1d 100644
--- a/spec/system/nfs_store/secure_viewer_enhancements_spec.rb
+++ b/spec/system/nfs_store/secure_viewer_enhancements_spec.rb
@@ -282,7 +282,7 @@ def open_secure_viewer(filename)
     expect(@container).to be_a(NfsStore::Manage::Container)
 
     # Upload a test file to the container for secure viewer tests
-    temp_dir = Rails.root.join('tmp', 'test_files')
+    temp_dir = Rails.root.join('tmp', 'test_files_secure_viewer')
     FileUtils.mkdir_p(temp_dir)
     @test_image_path = temp_dir.join('test-image.png')
     # Create a valid 100x100 PNG that the secure viewer can convert
@@ -307,7 +307,7 @@ def open_secure_viewer(filename)
 
   after :all do
     disable_active_panel_layout('test-columns-panel')
-    temp_dir = Rails.root.join('tmp', 'test_files')
+    temp_dir = Rails.root.join('tmp', 'test_files_secure_viewer')
     FileUtils.rm_rf(temp_dir)
   end
 

From af82c4574fda7deb633cf61a3d3ba0ddedbd5fc9 Mon Sep 17 00:00:00 2001
From: Phil <phil.ayres@consected.com>
Date: Sat, 4 Apr 2026 13:52:44 +0100
Subject: [PATCH 16/16] Fixed config notices enrichment, template null-safety,
 and save-trigger lifecycle regressions - fixes #986

---
 .../base_configuration.rb                     |  15 +-
 .../extra_option_configs/label.rb             |  10 +-
 .../extra_option_configs/trigger_tasks.rb     |  29 ++-
 app/models/option_configs/extra_options.rb    |  71 ++++++-
 app/models/save_triggers/log.rb               |   2 +-
 app/models/save_triggers/notify.rb            |   2 +-
 .../save_triggers/pull_external_data.rb       |   2 +-
 .../save_triggers/save_triggers_base.rb       |  50 ++++-
 app/models/save_triggers/update_this.rb       |   2 +-
 .../admin/app_types/_config_notices.html.erb  |   6 +-
 .../extra_option_configs/save_trigger_spec.rb |  54 ++++++
 .../extra_options_config_notices_spec.rb      | 181 ++++++++++++++++++
 spec/models/study_recruitment_setup_spec.rb   |   2 +-
 spec/system/admin/admin_parsed_config_spec.rb |  11 +-
 spec/system/advanced_search_spec.rb           |  17 +-
 .../api/save_trigger_api_endpoints_spec.rb    |   7 +
 spec/system/custom_editor_html_paste_spec.rb  |   2 +
 spec/system/player_data_entry_spec.rb         |  99 +++++-----
 18 files changed, 481 insertions(+), 81 deletions(-)
 create mode 100644 spec/models/option_configs/extra_options_config_notices_spec.rb

diff --git a/app/models/option_configs/extra_option_configs/base_configuration.rb b/app/models/option_configs/extra_option_configs/base_configuration.rb
index 9e46ad8989..dc7d1bc8d0 100644
--- a/app/models/option_configs/extra_option_configs/base_configuration.rb
+++ b/app/models/option_configs/extra_option_configs/base_configuration.rb
@@ -72,9 +72,11 @@ def setup_named_configurations
       # (not wrapped in {key => value}).
       # For classes with NamedConfiguration and Hash values, creates a NamedConfiguration.
       # For classes without (or with non-Hash values), stores the value directly.
+      # Tracks @current_field_name so failed_config can include field context.
       # @param [Symbol] sym_key - field name
       # @param [Object] value - field configuration value
       def add_named_configuration(sym_key, value)
+        @current_field_name = sym_key
         configurations[sym_key] = if self.class.const_defined?(:NamedConfiguration) && value.is_a?(Hash)
                                     nc = self.class::NamedConfiguration.new(self, use_hash_config: value)
                                     nc.validate_recognized_keys
@@ -82,6 +84,8 @@ def add_named_configuration(sym_key, value)
                                   else
                                     value
                                   end
+      ensure
+        @current_field_name = nil
       end
 
       # Assign a field configuration by key.
@@ -210,13 +214,22 @@ def persisted? = false
 
       # Error reporting — stores errors locally.
       # ExtraOptions collects these after initialization.
+      # Includes the current field name and raw config when available for context.
       # @param [Symbol] type - error category
       # @param [String] message - error description
       # @param [Object] extra_details - additional context
       # @param [Symbol] level - :error or :warn
       def failed_config(type, message, extra_details: nil, level: :error)
         target = (level == :warn ? config_warnings : config_errors)
-        target << { type:, message:, extra_details: }
+        entry = { type:, message:, extra_details: }
+        if @current_field_name
+          entry[:field_name] = @current_field_name
+          raw = hash_configuration[@current_field_name] if hash_configuration.is_a?(Hash)
+          entry[:field_config] = raw
+        elsif hash_configuration.present?
+          entry[:field_config] = hash_configuration
+        end
+        target << entry
       end
 
       private
diff --git a/app/models/option_configs/extra_option_configs/label.rb b/app/models/option_configs/extra_option_configs/label.rb
index e508442bb6..7f3da066fd 100644
--- a/app/models/option_configs/extra_option_configs/label.rb
+++ b/app/models/option_configs/extra_option_configs/label.rb
@@ -23,9 +23,17 @@ def self.prepare_config(raw, parent)
       end
 
       # Store the string value, defaulting to empty string.
+      # Warns when label is not a string (e.g. a Hash was provided).
       # @return [void]
       def setup_named_configurations
-        self.label = hash_configuration.is_a?(String) ? hash_configuration : ''
+        if hash_configuration.is_a?(String)
+          self.label = hash_configuration
+        else
+          self.label = ''
+          unless hash_configuration.blank?
+            failed_config(:label, "label must be a string, got #{hash_configuration.class.name.downcase}", level: :warn)
+          end
+        end
       end
     end
   end
diff --git a/app/models/option_configs/extra_option_configs/trigger_tasks.rb b/app/models/option_configs/extra_option_configs/trigger_tasks.rb
index 456bc7d3f9..85dc88ea19 100644
--- a/app/models/option_configs/extra_option_configs/trigger_tasks.rb
+++ b/app/models/option_configs/extra_option_configs/trigger_tasks.rb
@@ -24,11 +24,7 @@ class TriggerTasks < BaseConfiguration
       # @return [void]
       def setup_named_configurations
         raw = hash_configuration
-        self.tasks = if raw.is_a?(Array)
-                       raw
-                     else
-                       (raw || {}).symbolize_keys
-                     end
+        self.tasks = normalize_tasks(raw)
       end
 
       # Returns true when no tasks are defined.
@@ -41,6 +37,29 @@ def blank?
       def symbolize_keys
         tasks || {}
       end
+
+      private
+
+      def normalize_tasks(value)
+        return nil if value.nil?
+
+        case value
+        when Array
+          value.map { |item| normalize_tasks(item) }
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), normalized|
+            normalized[key.to_sym] = normalize_tasks(nested_value)
+          end
+        else
+          if value.respond_to?(:filtered_hash)
+            normalize_tasks(value.filtered_hash)
+          elsif value.respond_to?(:to_h) && !value.is_a?(String)
+            normalize_tasks(value.to_h)
+          else
+            value
+          end
+        end
+      end
     end
   end
 end
diff --git a/app/models/option_configs/extra_options.rb b/app/models/option_configs/extra_options.rb
index 239e306392..f3c3354209 100644
--- a/app/models/option_configs/extra_options.rb
+++ b/app/models/option_configs/extra_options.rb
@@ -113,7 +113,7 @@ def initialize(name, config, config_obj)
               send("#{key}=", instance)
             elsif config_class.store_processed_value?
               # Collect errors/warnings before discarding the instance
-              collect_instance_errors(instance)
+              collect_instance_errors(instance, registry_key: key)
               # Value-preprocessor class: store the processed value, not the object
               direct_attr = config_class.option_types[:direct]&.first || key
               send("#{key}=", instance.send(direct_attr))
@@ -184,11 +184,16 @@ def add_field_configs_from_standalone_defs
     # Used during registry initialization to capture errors before the instance
     # may be discarded (for store_processed_value? classes).
     # @param instance [BaseConfiguration] the config instance
-    def collect_instance_errors(instance)
+    # @param registry_key [Symbol] the config_class_registry key for this instance
+    def collect_instance_errors(instance, registry_key: nil)
       return unless instance.respond_to?(:config_errors)
 
-      config_errors.concat(instance.config_errors) if instance.config_errors.present?
-      config_warnings.concat(instance.config_warnings) if instance.config_warnings.present?
+      if instance.config_errors.present?
+        config_errors.concat(instance.config_errors.each { |e| enrich_config_notice(e, registry_key:) })
+      end
+      return unless instance.config_warnings.present?
+
+      config_warnings.concat(instance.config_warnings.each { |e| enrich_config_notice(e, registry_key:) })
     end
 
     # Collect config errors and warnings from field-keyed config instances
@@ -204,9 +209,61 @@ def collect_field_config_errors
         config_instance = send(key)
         next unless config_instance&.respond_to?(:config_errors)
 
-        config_errors.concat(config_instance.config_errors) if config_instance.config_errors.present?
-        config_warnings.concat(config_instance.config_warnings) if config_instance.config_warnings.present?
+        if config_instance.config_errors.present?
+          config_errors.concat(config_instance.config_errors.each { |e| enrich_config_notice(e, registry_key: key) })
+        end
+        if config_instance.config_warnings.present?
+          config_warnings.concat(config_instance.config_warnings.each { |e| enrich_config_notice(e, registry_key: key) })
+        end
+      end
+    end
+
+    # Enrich a config notice hash from a BaseConfiguration instance with
+    # the parent ExtraOptions context fields expected by the admin panel template.
+    # Mutates the hash in place, filling in missing keys.
+    #
+    # The template title renders: "{resource_name} - {name} - {type}"
+    # so :type should identify the config section (and field) for admin clarity,
+    # e.g. "caption_before > no_field". The :message should contain just the
+    # error detail without redundant context.
+    #
+    # :config_def is built as a YAML-friendly hash mirroring the config path,
+    # e.g. { caption_before: { no_field: { "do this" => true } } } so the
+    # admin panel preview shows exactly which YAML structure is problematic.
+    #
+    # @param notice [Hash] the config error/warning hash to enrich
+    # @param registry_key [Symbol, nil] the config_class_registry key (e.g. :caption_before)
+    def enrich_config_notice(notice, registry_key: nil)
+      notice[:name] ||= name
+      notice[:resource_name] ||= resource_name
+      notice[:config_class] ||= config_obj&.class&.name
+      notice[:config_object] ||= config_obj
+      notice[:config_resource_name] ||= config_obj&.class&.resource_name if config_obj
+
+      # Set :type to the config section path so the template heading identifies
+      # the source. field_name is the YAML key within the section (e.g. :no_field).
+      field_name = notice.delete(:field_name)
+      field_config = notice.delete(:field_config)
+      if registry_key
+        section = registry_key.to_s
+        section = "#{section} > #{field_name}" if field_name
+        notice[:type] = section
+
+        # Build config_def as a string-keyed nested hash showing the YAML path.
+        # Deep-stringify keys so the template renders clean YAML regardless of
+        # which YAML method is used.
+        unless notice[:config_def].present?
+          cd = if field_name
+                 { registry_key => { field_name => field_config } }
+               elsif field_config
+                 { registry_key => field_config }
+               else
+                 {}
+               end
+          notice[:config_def] = cd.deep_stringify_keys
+        end
       end
+      notice[:config_def] ||= {}
     end
 
     # Check if any of the configs were bad
@@ -537,7 +594,7 @@ def calc_valid_if(action_type, obj, return_failures: nil)
         raise FphsException, "incorrect action type requested in calc_valid_if #{action_type}"
       end
 
-      ci = self.valid_if[:"on_#{action_type}"]
+      ci = valid_if[:"on_#{action_type}"]
       Rails.logger.debug "Checking calc_valid_if on #{obj} with #{ci}"
       ca = ConditionalActions.new(ci, obj, return_failures:)
       ca.calc_action_if
diff --git a/app/models/save_triggers/log.rb b/app/models/save_triggers/log.rb
index 8fa5967c66..3dce4b889f 100644
--- a/app/models/save_triggers/log.rb
+++ b/app/models/save_triggers/log.rb
@@ -17,7 +17,7 @@ class SaveTriggers::Log < SaveTriggers::SaveTriggersBase
   def initialize(config, item)
     super
 
-    @model_defs = config
+    @model_defs = self.config
   end
 
   def perform
diff --git a/app/models/save_triggers/notify.rb b/app/models/save_triggers/notify.rb
index dd37a1afa3..cb31425057 100644
--- a/app/models/save_triggers/notify.rb
+++ b/app/models/save_triggers/notify.rb
@@ -17,7 +17,7 @@ def self.allow_future_processing
   def initialize(config, item)
     super
 
-    @model_defs = config.deep_dup
+    @model_defs = self.config.deep_dup
     @model_defs = [@model_defs] unless @model_defs.is_a? Array
   end
 
diff --git a/app/models/save_triggers/pull_external_data.rb b/app/models/save_triggers/pull_external_data.rb
index 61d4a9e820..fd2e80744b 100644
--- a/app/models/save_triggers/pull_external_data.rb
+++ b/app/models/save_triggers/pull_external_data.rb
@@ -11,7 +11,7 @@ def self.config_def(if_extras: {}); end
   def initialize(config, item)
     super
 
-    @model_defs = config
+    @model_defs = self.config
   end
 
   def perform
diff --git a/app/models/save_triggers/save_triggers_base.rb b/app/models/save_triggers/save_triggers_base.rb
index 1e8073a1f9..c9e4177105 100644
--- a/app/models/save_triggers/save_triggers_base.rb
+++ b/app/models/save_triggers/save_triggers_base.rb
@@ -5,15 +5,18 @@ class SaveTriggers::SaveTriggersBase
   attr_accessor :config, :user, :item, :master, :model_defs, :this_config, :in_master
 
   def initialize(config, item)
+    on_complete_triggers, on_failure_triggers = extract_lifecycle_hooks(config)
+
+    config = normalize_trigger_config(config)
     self.config = config
     raise FphsException, 'save_trigger configuration must be a Hash' unless config.is_a?(Hash) || config.is_a?(Array)
 
     raise FphsException, 'save_trigger item must be set' unless item
 
-    # Extract lifecycle hooks before subclasses process the config.
-    # This ensures on_complete and on_failure are automatically available
-    # to all trigger types including future implementations.
-    extract_lifecycle_hooks(config)
+    # Normalize extracted lifecycle hooks so lifecycle dispatch uses the same
+    # plain Ruby hashes/arrays as the main trigger config.
+    @on_complete_triggers = normalize_trigger_config(on_complete_triggers)
+    @on_failure_triggers = normalize_trigger_config(on_failure_triggers)
 
     self.item = item
     self.master = item.master if item.respond_to? :master
@@ -220,6 +223,34 @@ def self.config_def(if_extras: nil); end
 
   private
 
+  def normalize_trigger_config(value)
+    return nil if value.nil?
+
+    case value
+    when Array
+      value.map! { |entry| normalize_trigger_config(entry) }
+    when Hash
+      normalized = value.each_with_object({}) do |(key, nested_value), result|
+        result[key.to_sym] = normalize_trigger_config(nested_value)
+      end
+      value.clear
+      value.merge!(normalized)
+      value
+    else
+      if value.respond_to?(:filtered_hash)
+        normalize_trigger_config(value.filtered_hash)
+      elsif value.respond_to?(:conditions)
+        normalize_trigger_config(value.conditions)
+      elsif value.respond_to?(:symbolize_keys) && !value.is_a?(String)
+        normalize_trigger_config(value.symbolize_keys)
+      elsif value.respond_to?(:to_h) && !value.is_a?(String)
+        normalize_trigger_config(value.to_h)
+      else
+        value
+      end
+    end
+  end
+
   #
   # Extract on_complete and on_failure from the config hash for lifecycle processing.
   # These keys are removed from the config so subclass trigger processing
@@ -229,10 +260,15 @@ def self.config_def(if_extras: nil); end
   # continue to function correctly.
   # @param [Hash | Array] trigger_config
   def extract_lifecycle_hooks(trigger_config)
-    return unless trigger_config.is_a?(Hash)
+    return [nil, nil] unless trigger_config.is_a?(Hash)
+
+    on_complete = trigger_config.delete(:on_complete)
+    on_complete ||= trigger_config.delete('on_complete')
+
+    on_failure = trigger_config.delete(:on_failure)
+    on_failure ||= trigger_config.delete('on_failure')
 
-    @on_complete_triggers = trigger_config.delete(:on_complete)
-    @on_failure_triggers = trigger_config.delete(:on_failure)
+    [on_complete, on_failure]
   end
 
   #
diff --git a/app/models/save_triggers/update_this.rb b/app/models/save_triggers/update_this.rb
index efcd6170f5..de552718c8 100644
--- a/app/models/save_triggers/update_this.rb
+++ b/app/models/save_triggers/update_this.rb
@@ -26,7 +26,7 @@ def self.config_def(if_extras: {})
   def initialize(config, item)
     super
 
-    @model_defs = config
+    @model_defs = self.config
   end
 
   def perform
diff --git a/app/views/admin/app_types/_config_notices.html.erb b/app/views/admin/app_types/_config_notices.html.erb
index f42a743dfb..ee04e847c4 100644
--- a/app/views/admin/app_types/_config_notices.html.erb
+++ b/app/views/admin/app_types/_config_notices.html.erb
@@ -7,11 +7,11 @@
   prev_id = nil
   sorted_cns = @config_notices.sort_by { |ce| "#{ce[:resource_name]}--#{ce[:name]}--#{ce[:type]}" }
   sorted_cns.each do |ce| 
-    el_id = "app-type-config-notices-body--#{ce[:resource_name]}--#{ce[:name].id_hyphenate}-#{ce[:type].id_hyphenate}"
+    el_id = "app-type-config-notices-body--#{ce[:resource_name]}--#{ce[:name].to_s.id_hyphenate}-#{ce[:type].to_s.id_hyphenate}"
     next if el_id == prev_id
 
     prev_id = el_id
-    head_el_id = "app-type-config-notices-heading--#{ce[:name].id_hyphenate}-#{ce[:type].id_hyphenate}"
+    head_el_id = "app-type-config-notices-heading--#{ce[:name].to_s.id_hyphenate}-#{ce[:type].to_s.id_hyphenate}"
     title = "<span class=\"activity-list-name\">#{ce[:resource_name]} - #{ce[:name]}</span> - #{ce[:type]}".html_safe
   %>
     <div class="panel panel-default">
@@ -35,7 +35,7 @@
               <% end %>
           <div class="config-notice">
             <p><%= cn[:message] %></p>
-            <pre><%= cn[:config_def].to_yaml.sub("---\n",'') %></pre>
+            <pre><%= String.yaml_dump(cn[:config_def]) %></pre>
           </div>
           <% end %>
         </div>
diff --git a/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb b/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
index c61531655c..0ae080a2ee 100644
--- a/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
+++ b/spec/models/option_configs/extra_option_configs/save_trigger_spec.rb
@@ -199,5 +199,59 @@
       expect(eo.save_trigger).to be_a OptionConfigs::ExtraOptionConfigs::SaveTrigger
       expect(eo.save_trigger[:on_create]).to be_a Array
     end
+
+    it 'normalizes nested create_reference trigger lists to plain hashes and arrays' do
+      eo = config_for(<<~YAML)
+        default:
+          save_trigger:
+            on_create:
+              create_reference:
+                - activity_log__play_ipa_assignment_inex_checklist:
+                    in: master
+                    with:
+                      extra_log_type: phone_screen_review
+                      force_create: true
+                - activity_log__play_ipa_assignment:
+                    if:
+                      all:
+                        embedded_item:
+                          allow_future_comms_yes_no:
+                            -
+                            - ''
+                            - 'no'
+                      any:
+                        embedded_item:
+                          select_still_interested: 'no'
+                          select_intro_interested: not interested
+                    in: master
+                    with:
+                      extra_log_type: finalized_phone_screen
+                    notify:
+                      - type: email
+                        role: email - inex pi
+      YAML
+
+      on_create = eo.save_trigger[:on_create]
+
+      expect(on_create).to be_a(Hash)
+      expect(on_create[:create_reference]).to be_an(Array)
+      expect(on_create[:create_reference].first).to be_a(Hash)
+      expect(on_create[:create_reference].first[:activity_log__play_ipa_assignment_inex_checklist]).to be_a(Hash)
+      expect(on_create[:create_reference].last[:activity_log__play_ipa_assignment][:if]).to eq(
+        all: {
+          embedded_item: {
+            allow_future_comms_yes_no: [nil, '', 'no']
+          }
+        },
+        any: {
+          embedded_item: {
+            select_still_interested: 'no',
+            select_intro_interested: 'not interested'
+          }
+        }
+      )
+      expect(on_create[:create_reference].last[:activity_log__play_ipa_assignment][:notify]).to be_an(Array)
+      expect(on_create[:create_reference].last[:activity_log__play_ipa_assignment][:notify].first).to be_a(Hash)
+    end
   end
 end
diff --git a/spec/models/option_configs/extra_options_config_notices_spec.rb b/spec/models/option_configs/extra_options_config_notices_spec.rb
new file mode 100644
index 0000000000..ef875390ad
--- /dev/null
+++ b/spec/models/option_configs/extra_options_config_notices_spec.rb
@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require './db/table_generators/dynamic_models_table'
+
+# Tests for config notice enrichment in ExtraOptions.
+# Verifies that errors and warnings produced by BaseConfiguration subclasses
+# are enriched with the parent context fields required by the admin panel
+# template (_config_notices.html.erb): :name, :resource_name, :config_class,
+# :config_object, :config_resource_name, :config_def.
+# Also verifies that messages include config section and field name context
+# so administrators can identify the source of configuration problems.
+RSpec.describe 'ExtraOptions config notice enrichment', type: :model do
+  include MasterSupport
+  include ModelSupport
+  include DynamicModelSupport
+  include ExtraOptionConfigsSupport
+
+  before(:each) do
+    create_admin
+    create_user
+    setup_access :trackers
+    setup_access :tracker_histories
+    @dm = generate_test_dynamic_model
+    setup_access :dynamic_model__test_created_by_recs, user: @user
+  end
+
+  describe 'caption_before with unrecognized attributes' do
+    let(:yaml) do
+      <<~YAML
+        default:
+          caption_before:
+            no_field:
+              do this: true
+      YAML
+    end
+
+    it 'enriches warnings with all template-required fields' do
+      oc = config_for(yaml)
+      warnings = oc.config_warnings
+
+      expect(warnings).not_to be_empty
+
+      warning = warnings.find { |w| w[:message].include?('do this') }
+      expect(warning).not_to be_nil
+
+      # All fields required by _config_notices.html.erb must be present
+      expect(warning[:name]).to eq :default
+      expect(warning[:resource_name]).to be_present
+      expect(warning[:config_class]).to be_present
+      expect(warning[:config_object]).to eq @dm
+      expect(warning[:config_resource_name]).to be_present
+      expect(warning[:config_def]).to be_a(Hash)
+    end
+
+    it 'sets :type to config section path for template heading' do
+      oc = config_for(yaml)
+      warning = oc.config_warnings.find { |w| w[:message].include?('do this') }
+
+      # :type identifies the config section and field for the template title
+      # Template renders: "{resource_name} - {name} - {type}"
+      expect(warning[:type]).to eq 'caption_before > no_field'
+      # Message is just the error detail, no redundant prefix
+      expect(warning[:message]).to eq "unrecognized attribute 'do this'"
+    end
+
+    it 'builds config_def as a string-keyed nested hash showing the config path' do
+      oc = config_for(yaml)
+      warning = oc.config_warnings.find { |w| w[:message].include?('do this') }
+
+      # config_def mirrors the YAML structure with string keys for clean YAML rendering
+      expect(warning[:config_def]).to eq('caption_before' => { 'no_field' => { 'do this' => true } })
+      # Renders clean YAML without symbol prefixes
+      yaml_output = warning[:config_def].to_yaml
+      expect(yaml_output).to include('caption_before:')
+      expect(yaml_output).to include('no_field:')
+      expect(yaml_output).to include('do this:')
+      expect(yaml_output).not_to include(':caption_before')
+    end
+  end
+
+  describe 'label with non-string value' do
+    let(:yaml) do
+      <<~YAML
+        default:
+          label:
+            is_wrong: true
+      YAML
+    end
+
+    it 'produces a warning with label section as :type' do
+      oc = config_for(yaml)
+      warnings = oc.config_warnings
+
+      label_warning = warnings.find { |w| w[:message].include?('label must be a string') }
+      expect(label_warning).not_to be_nil
+      expect(label_warning[:type]).to eq 'label'
+      expect(label_warning[:message]).to eq 'label must be a string, got hash'
+    end
+
+    it 'builds config_def showing the label config value with string keys' do
+      oc = config_for(yaml)
+      label_warning = oc.config_warnings.find { |w| w[:message].include?('label must be a string') }
+
+      # Shows what was passed as the label value, with string keys
+      expect(label_warning[:config_def]).to eq('label' => { 'is_wrong' => true })
+      yaml_output = label_warning[:config_def].to_yaml
+      expect(yaml_output).to include('label:')
+      expect(yaml_output).not_to include(':label')
+    end
+
+    it 'enriches label warning with all template-required fields' do
+      oc = config_for(yaml)
+      label_warning = oc.config_warnings.find { |w| w[:message].include?('label must be a string') }
+
+      expect(label_warning[:name]).to eq :default
+      expect(label_warning[:resource_name]).to be_present
+      expect(label_warning[:config_class]).to be_present
+      expect(label_warning[:config_object]).to eq @dm
+      expect(label_warning[:config_def]).to be_a(Hash)
+    end
+  end
+
+  describe 'all_option_configs_notices returns enriched notices' do
+    let(:yaml) do
+      <<~YAML
+        default:
+          label:
+            is_wrong: true
+          caption_before:
+            no_field:
+              do this: true
+      YAML
+    end
+
+    it 'returns notices with all template-required keys via all_option_configs_notices' do
+      @dm.update!(options: yaml, current_admin: @admin)
+      notices = OptionConfigs::ExtraOptions.all_option_configs_notices(@dm)
+
+      expect(notices).not_to be_nil
+      expect(notices.length).to be >= 2
+
+      notices.each do |notice|
+        expect(notice).to have_key(:name), "notice missing :name — #{notice[:message]}"
+        expect(notice).to have_key(:resource_name), "notice missing :resource_name — #{notice[:message]}"
+        expect(notice).to have_key(:config_def), "notice missing :config_def — #{notice[:message]}"
+        expect(notice[:name]).to be_present, "notice :name is blank — #{notice[:message]}"
+      end
+    end
+
+    it 'does not raise when template calls .to_s.id_hyphenate on notice fields' do
+      @dm.update!(options: yaml, current_admin: @admin)
+      notices = OptionConfigs::ExtraOptions.all_option_configs_notices(@dm)
+
+      notices.each do |notice|
+        # Simulate what _config_notices.html.erb does
+        expect { notice[:name].to_s.id_hyphenate }.not_to raise_error
+        expect { notice[:type].to_s.id_hyphenate }.not_to raise_error
+        expect { notice[:resource_name].to_s }.not_to raise_error
+        expect { notice[:config_def].to_yaml }.not_to raise_error
+      end
+    end
+  end
+
+  describe 'valid configuration produces no notices' do
+    let(:yaml) do
+      <<~YAML
+        default:
+          label: My Label
+          caption_before:
+            test1: Some caption text
+      YAML
+    end
+
+    it 'does not produce errors or warnings for valid config' do
+      oc = config_for(yaml)
+      expect(oc.config_errors).to be_empty
+      expect(oc.config_warnings).to be_empty
+    end
+  end
+end
diff --git a/spec/models/study_recruitment_setup_spec.rb b/spec/models/study_recruitment_setup_spec.rb
index 0693c0824a..214c13d1a3 100644
--- a/spec/models/study_recruitment_setup_spec.rb
+++ b/spec/models/study_recruitment_setup_spec.rb
@@ -30,4 +30,4 @@
       end
     end
   end
-end
\ No newline at end of file
+end
diff --git a/spec/system/admin/admin_parsed_config_spec.rb b/spec/system/admin/admin_parsed_config_spec.rb
index a0a31bb080..5c11b32e06 100644
--- a/spec/system/admin/admin_parsed_config_spec.rb
+++ b/spec/system/admin/admin_parsed_config_spec.rb
@@ -15,11 +15,14 @@
 
   describe 'dynamic models' do
     it 'displays parsed config tab with line numbers' do
-      # Find any existing dynamic model to test with
-      dm = DynamicModel.active.first
+      # Use a dynamic model that actually renders parsed configuration text.
+      dm = DynamicModel.active.detect do |candidate|
+        candidate.class.options_provider.parsed_options_text(candidate).present?
+      rescue StandardError
+        false
+      end
 
-      # Skip test if no dynamic models exist
-      skip 'No active dynamic models found' unless dm
+      skip 'No active dynamic models with parsed config found' unless dm
 
       admin_sign_in_with_2fa
 
diff --git a/spec/system/advanced_search_spec.rb b/spec/system/advanced_search_spec.rb
index 3e0abfe04e..23e13a7a28 100644
--- a/spec/system/advanced_search_spec.rb
+++ b/spec/system/advanced_search_spec.rb
@@ -167,7 +167,8 @@
 
     within '#advanced_search_master' do
       select protocol.name, from: 'master_trackers_attributes_0_protocol_id'
-      select sp.name, from: 'master_trackers_attributes_0_sub_process_id'
+      expect(page).to have_css("#master_trackers_attributes_0_sub_process_id option[value='#{sp.id}']", wait: 10)
+      find("#master_trackers_attributes_0_sub_process_id option[value='#{sp.id}']").select_option
     end
 
     # wait a while, maybe
@@ -199,8 +200,20 @@
       # h = el['data-target'].split('#').last
       # have_css("##{h}.collapse.in")
       # find "##{h}.collapse.in", wait: 5
+      expand_master_record_tab('tracker') unless page.has_css?("##{h}.tracker-block.collapse.in", wait: 3)
       have_css "##{h}.tracker-block.collapse.in"
-      expect(page).to have_css "##{h} div.tracker-block table.tracker-tree-results tbody[data-tracker-protocol='#{protocol.name.downcase}'] .tracker-protocol_name", text: /#{protocol.name}/i
+      tracker_protocol_selector = "##{h} div.tracker-block table.tracker-tree-results tbody[data-tracker-protocol='#{protocol.name.downcase}'] .tracker-protocol_name"
+
+      unless page.has_css?(tracker_protocol_selector, text: /#{protocol.name}/i, wait: 3)
+        view_as_events = first("##{h} div.tracker-block a[title='view as events']", wait: 5)
+        if view_as_events
+          scroll_into_view(view_as_events)
+          view_as_events.click
+          finish_page_loading
+        end
+      end
+
+      expect(page).to have_css tracker_protocol_selector, text: /#{protocol.name}/i
       expect(page).to have_css "##{h} div.tracker-block table.tracker-tree-results tbody[data-tracker-protocol='#{protocol.name.downcase}'] .tracker-sub_process_name", text: /#{sp.name}/i
 
       done += 1
diff --git a/spec/system/api/save_trigger_api_endpoints_spec.rb b/spec/system/api/save_trigger_api_endpoints_spec.rb
index efbd427c88..0d57a1c221 100644
--- a/spec/system/api/save_trigger_api_endpoints_spec.rb
+++ b/spec/system/api/save_trigger_api_endpoints_spec.rb
@@ -84,6 +84,13 @@
     expect(@target_record.id).to be_present
   end
 
+  before(:each) do
+    # Other system specs reload routes while running in parallel. Re-register the
+    # dynamic model routes here so the Capybara server always has the API endpoints.
+    DynamicModel.routes_load
+    Rails.application.routes_reloader.reload!
+  end
+
   #
   # Capybara test server URL (e.g., "http://127.0.0.1:12345")
   # @return [String]
diff --git a/spec/system/custom_editor_html_paste_spec.rb b/spec/system/custom_editor_html_paste_spec.rb
index a924a6b7dc..40a5d3b7f5 100644
--- a/spec/system/custom_editor_html_paste_spec.rb
+++ b/spec/system/custom_editor_html_paste_spec.rb
@@ -532,6 +532,7 @@
         editor.click
         sleep 0.3
 
+        expect(page).to have_css('.btn-toolbar[data-role="editor-toolbar"]', visible: true, wait: 10)
         toolbar = find('.btn-toolbar[data-role="editor-toolbar"]', match: :first)
         bullet_button = toolbar.find("[data-edit='insertunorderedlist']")
         bullet_button.click
@@ -555,6 +556,7 @@
         editor.click
         sleep 0.3
 
+        expect(page).to have_css('.btn-toolbar[data-role="editor-toolbar"]', visible: true, wait: 10)
         toolbar = find('.btn-toolbar[data-role="editor-toolbar"]', match: :first)
         number_button = toolbar.find("[data-edit='insertorderedlist']")
         number_button.click
diff --git a/spec/system/player_data_entry_spec.rb b/spec/system/player_data_entry_spec.rb
index 925c59959c..3a2e609966 100644
--- a/spec/system/player_data_entry_spec.rb
+++ b/spec/system/player_data_entry_spec.rb
@@ -190,7 +190,7 @@ def edit_player_info(fname, lname, startyear, endyear, _source)
     endyear ||= ''
     endyear = endyear.to_s
 
-    within 'form.edit_player_info' do
+    within player_info_form_selector do
       fill_in 'First name', with: fname
       fill_in 'Last name', with: lname
       fill_in 'Start year', with: startyear
@@ -219,6 +219,13 @@ def edit_player_info(fname, lname, startyear, endyear, _source)
     expect(page).to have_css(".player-info-item a[title='edit']")
   end
 
+  def player_info_form_selector
+    return 'form.edit_player_info' if page.has_css?('form.edit_player_info', wait: 3)
+    return 'form#new_player_info' if page.has_css?('form#new_player_info', wait: 3)
+
+    raise 'Could not find player info form'
+  end
+
   #
   # A college field provides both typeahead and free text entry.
   # This method tests both for the allow_missing option is true. The free text entry
@@ -304,6 +311,33 @@ def search_dob(m, d, y)
     have_css(".player-info-item a[title='edit']")
   end
 
+  def ensure_player_info_item_visible
+    return if page.has_css?('.player-info-item', wait: 3)
+
+    expanders = all('a.master-expander', wait: 10)
+    expect(expanders).not_to be_empty
+    open_player_element(expanders.first, expanders)
+    expand_master_record_tab('details') unless page.has_css?('.player-info-item', wait: 3)
+    return if page.has_css?('.player-info-item', wait: 10)
+    return if page.has_css?('.add-item-button', text: /player info/i, wait: 5)
+
+    expect(page).to have_css('.player-info-item', wait: 10)
+  end
+
+  def open_player_info_form
+    ensure_player_info_item_visible
+
+    if page.has_css?(".player-info-item a[title='edit']", wait: 3)
+      all(".player-info-item a[title='edit']").first.click
+    else
+      add_button = find('.add-item-button', text: /player info/i, match: :first, wait: 10)
+      scroll_into_view(add_button)
+      add_button.click
+    end
+
+    expect(page).to have_css('form.edit_player_info, form#new_player_info', wait: 10)
+  end
+
   def add_player_msid(player)
     # create Master
     expect(page).to have_css("a[href='/masters/new']")
@@ -319,11 +353,7 @@ def add_player_msid(player)
     # edit player info data
 
     expect(page).to have_css('#master_results_block')
-    expect(page).to have_css('.player-info-item')
-    b = all ".player-info-item a[title='edit']"
-    b.first.click
-
-    expect(page).to have_css('form.edit_player_info')
+    open_player_info_form
 
     edit_player_info player[:first_name], player[:last_name], player[:start_year], player[:end_year], player[:source]
 
@@ -393,13 +423,11 @@ def add_player_msid(player)
     # edit player info data
 
     expect(page).to have_css('#master_results_block')
-    expect(page).to have_css('.player-info-item')
+    open_player_info_form
     sleep 1
-    b = all ".player-info-item a[title='edit']"
-    b.first.click
     sleep 0.5 # Allow edit form to load via AJAX
 
-    expect(page).to have_css('form.edit_player_info', wait: 10)
+    expect(page).to have_css('form.edit_player_info, form#new_player_info', wait: 10)
 
     item_type = 'player_infos_source'
     sources = Classification::GeneralSelection.where(item_type: item_type)
@@ -471,46 +499,25 @@ def add_player_msid(player)
     scroll_into_view af
     af.click
 
-    sleep 1
-    # Trigger the chosen drop down
-    i = 'ul.chosen-choices .search-field input.default'
-    debug_state('chosen_dropdown_trigger', 'Trigger Chosen drop down for item flags') unless page.has_css?(i, wait: 5)
+    expect(page).to have_css('.item-flags-block form', wait: 10)
 
-    expect(page).to have_css(i)
-    sleep 1
-    f = find(i)
-    f.click
-
-    # An absolutely positioned drop down is now shown. Interact with this instead
-    i = 'body > .chosen-container ul.chosen-choices .search-field input'
-    debug_state('chosen_dropdown_input', 'Chosen drop down for item flags') unless page.has_css?(i, wait: 5)
-    expect(page).to have_css(i)
-    f = find(i)
-
-    f.send_keys('f')
-    f.send_keys('o')
+    flag_name = Classification::ItemFlagName.enabled.where(item_type: 'player_info').pluck(:name).find { |name| name.match?(/\Afo/i) }
+    expect(flag_name).not_to be_nil
 
-    expect(page).to have_css('body > .chosen-container ul.chosen-results')
-    res = page.all('body > .chosen-container ul.chosen-results li.active-result')
+    page.execute_script(<<~JS, flag_name)
+      var select = document.getElementById('item_flag_item_flag_name_id');
+      if (!select) return;
+      var wanted = arguments[0].toLowerCase();
 
-    expect(res.length).to be > 0
-    res.each do |r|
-      expect(r.text).to match(/fo.+/)
-    end
-
-    text1 = res.first.text
-    res.first.click
+      Array.from(select.options).forEach(function(option) {
+        option.selected = option.text.trim().toLowerCase() === wanted;
+      });
 
-    sleep 1
-    # tag = 'body > .chosen-container ul.chosen-choices li.search-choice span'
-    # expect(page).to have_css(tag)
-    # ftag = find(tag)
-    # expect(ftag.text).to eq(res.first.text)
+      $(select).trigger('chosen:updated');
+      $(select).trigger('change');
+    JS
 
-    # Handle the absolutely positioned chosen drop down
-    page.find('body > .chosen-container ul.chosen-choices').click
-    # Clear the chosen box
-    page.all('h4.list-group-item-heading').first.click
+    text1 = flag_name
 
     within('.item-flags-block form') do
       click_button 'Save Item flag'
@@ -518,7 +525,7 @@ def add_player_msid(player)
 
     # The absolutely positioned chosen has gone away. Search for the standard one
     tag = '.chosen-container ul.chosen-choices li.search-choice span'
-    expect(page).to have_css(tag)
+    expect(page).to have_css(tag, text: text1, wait: 10)
     ftag = find(tag)
     expect(ftag.text).to eq(text1)