typed_eav 0.1.0 → 0.2.0

data/lib/typed_eav/config.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "active_support/configurable"
-
 module TypedEAV
   # Gem-level configuration for field type registration.
   #
@@ -12,15 +10,46 @@ module TypedEAV
   # Accessible from anywhere via `TypedEAV.config` (which returns this
   # class; class-level `field_types` / `register_field_type` / `field_class_for`
   # / `type_names` methods are defined below).
+  #
+  # Implementation note: class-level accessors are hand-rolled (plain class
+  # instance variables behind reader/writer methods) rather than provided by
+  # ActiveSupport::Configurable. Configurable was deprecated without
+  # replacement in Rails 8.1 and will be removed in Rails 8.2; rolling our
+  # own keeps the public API stable across the migration. The `defined?(@var)`
+  # idiom on the readers preserves the "never set vs explicitly nil"
+  # distinction that callers rely on (e.g., spec_helper's snapshot/restore
+  # hook explicitly assigns `nil` and expects the reader to return `nil`,
+  # not silently fall through to a default).
   class Config
-    include ActiveSupport::Configurable
-
     # Default ambient-scope resolver. Auto-detects `acts_as_tenant` when
     # loaded so AAT users get zero-config behavior. Apps using any other
     # multi-tenancy primitive (Rails `Current` attributes, a subdomain
     # lookup, a thread-local, etc.) override via `TypedEAV.configure`.
+    #
+    # ## Return-value contract (Phase 1, breaking change from v0.1.x)
+    #
+    # Returns either `nil` (no resolver / opt-out) or a 2-element Array
+    # `[scope, parent_scope]`. The `acts_as_tenant` gem has no
+    # `parent_scope` analog, so the parent slot is unconditionally `nil`.
+    # When AAT is not loaded we return `nil` (the sentinel: no resolver
+    # consulted). When AAT is loaded but `current_tenant` is itself nil
+    # we return `[nil, nil]` (the sentinel: AAT consulted, no tenant) —
+    # intentionally NOT auto-collapsed to nil, to preserve the distinction
+    # between "no resolver" and "resolver returned nothing".
+    #
+    # ## Migration note for v0.1.x custom resolvers
+    #
+    # Custom resolver lambdas configured via `Config.scope_resolver = ->{ ... }`
+    # MUST be updated to return a 2-element Array `[scope, parent_scope]`
+    # (or `nil`). A bare-scalar return — the v0.1.x shape — raises
+    # `ArgumentError` from `TypedEAV.current_scope`. The shim alternative
+    # (auto-coerce scalar to `[scalar, nil]`) was rejected during Phase 1
+    # design; we want the breaking change to be loud, not silent. See the
+    # CHANGELOG and README migration section for the upgrade pattern.
     DEFAULT_SCOPE_RESOLVER = lambda {
-      ::ActsAsTenant.current_tenant if defined?(::ActsAsTenant)
+      next nil unless defined?(::ActsAsTenant)
+
+      [::ActsAsTenant.current_tenant, nil]
     }
 
     # Map of type names to their STI class names.
@@ -31,37 +60,182 @@ module TypedEAV
       integer: "TypedEAV::Field::Integer",
       decimal: "TypedEAV::Field::Decimal",
       boolean: "TypedEAV::Field::Boolean",
+      currency: "TypedEAV::Field::Currency",
       date: "TypedEAV::Field::Date",
       date_time: "TypedEAV::Field::DateTime",
       select: "TypedEAV::Field::Select",
       multi_select: "TypedEAV::Field::MultiSelect",
+      percentage: "TypedEAV::Field::Percentage",
+      reference: "TypedEAV::Field::Reference",
       integer_array: "TypedEAV::Field::IntegerArray",
       decimal_array: "TypedEAV::Field::DecimalArray",
       text_array: "TypedEAV::Field::TextArray",
       date_array: "TypedEAV::Field::DateArray",
       email: "TypedEAV::Field::Email",
+      file: "TypedEAV::Field::File",
+      image: "TypedEAV::Field::Image",
       url: "TypedEAV::Field::Url",
       color: "TypedEAV::Field::Color",
       json: "TypedEAV::Field::Json",
     }.freeze
 
-    # Mutable registry of type_name => class_name pairs. Seeded from
-    # BUILTIN_FIELD_TYPES on first access; extended via register_field_type.
-    config_accessor(:field_types) { BUILTIN_FIELD_TYPES.dup }
+    class << self
+      # Mutable registry of type_name => class_name pairs. Seeded from
+      # BUILTIN_FIELD_TYPES on first access; extended via register_field_type.
+      def field_types
+        @field_types ||= BUILTIN_FIELD_TYPES.dup
+      end
+      attr_writer :field_types # rubocop:disable Style/AccessorGrouping
+
+      # Callable returning the ambient scope (partition key) for class-level
+      # queries. Invoked by `TypedEAV.current_scope` when no explicit
+      # `scope:` kwarg is passed and no `with_scope` block is active.
+      #
+      # ## Resolver contract (strict — Phase 1 breaking change)
+      #
+      # The resolver MUST return either:
+      #   - `nil`                              — opt out / no scope to resolve
+      #   - `[scope, parent_scope]` 2-Array    — both elements may be `nil`
+      #
+      # Any other shape — most importantly a bare scalar (the v0.1.x shape) —
+      # raises `ArgumentError` in `TypedEAV.current_scope`. There is no
+      # auto-coercion. `parent_scope` non-nil + `scope` nil (orphan parent)
+      # is rejected by model-level validators (plans 03 / 04), NOT here —
+      # this layer is a contract surface, not a validation surface.
+      #
+      # Note: `TypedEAV.with_scope(value)` is a DIFFERENT surface — its block
+      # API is BC-permissive and accepts a scalar. The resolver-callable
+      # contract is strict; the `with_scope` block contract is not. Both
+      # surfaces, two contracts.
+      def scope_resolver
+        defined?(@scope_resolver) ? @scope_resolver : DEFAULT_SCOPE_RESOLVER
+      end
+      attr_writer :scope_resolver # rubocop:disable Style/AccessorGrouping
+
+      # When true, class-level queries on a model that declared
+      # `has_typed_eav scope_method: ...` raise `TypedEAV::ScopeRequired`
+      # if no scope can be resolved (explicit arg, active `with_scope` block,
+      # or configured resolver all returned nil). Bypass per-call via
+      # `TypedEAV.unscoped { ... }`.
+      def require_scope
+        defined?(@require_scope) ? @require_scope : true
+      end
+      attr_writer :require_scope # rubocop:disable Style/AccessorGrouping
+
+      # Master kill-switch for Phase 04 versioning. When false (default), the
+      # Phase 04 internal subscriber is NOT registered with EventDispatcher
+      # at engine boot — zero overhead for apps that don't use versioning.
+      # When true, the subscriber registers but only writes a version row
+      # when value.entity_type belongs to a host model that opted in via
+      # `has_typed_eav versioned: true` (per-entity opt-in flows through
+      # Registry; both layers land in plan 04-02).
+      #
+      # Decoupling the master switch from the per-entity decision: disabling
+      # for all is one toggle here; enabling for some is a per-host decision
+      # in `has_typed_eav`. Apps that want to A/B-test versioning across
+      # environments toggle this single flag.
+      #
+      # Default false because the schema migration only matters for apps that
+      # opt in. A v0.1.x deployment that pulls in Phase 04 without changing
+      # any config or model declarations sees no behavior change — the
+      # subscriber doesn't register, no version rows are written, no perf
+      # impact at all. The migration is still copied (idempotent), but the
+      # table sits empty.
+      def versioning
+        defined?(@versioning) ? @versioning : false
+      end
+      attr_writer :versioning # rubocop:disable Style/AccessorGrouping
+
+      # Permissive actor resolver. Mirrors the `scope_resolver` callable
+      # shape (lib/typed_eav.rb:94: `Config.scope_resolver&.call`) but the
+      # return contract is permissive: any value the app chooses (AR object,
+      # integer, string, nil) is acceptable, and nil is the documented
+      # fail-permissive sentinel.
+      #
+      # Called from TypedEAV::Versioning::Subscriber (plan 04-02) once per
+      # version row write: `actor = TypedEAV.config.actor_resolver&.call`.
+      # The return is coerced via `normalize_one`-style String coercion
+      # (gem's existing pattern at lib/typed_eav.rb:239-243) before storage
+      # in the typed_eav_value_versions.changed_by column. nil flows through
+      # as nil — the column is nullable (db/migrate/20260505000000).
+      #
+      # Why permissive (vs. scope_resolver's strict return contract):
+      # missing scope is a tenant-isolation hazard (catastrophic, fail-
+      # closed). Missing actor is a degraded audit log (recoverable,
+      # sometimes legitimate — system writes, migrations, console).
+      # Forcing every Versioned write to have an actor would reject every
+      # console save, every migration backfill, every job that didn't set
+      # `with_context(actor: ...)` — hostile defaults for a gem.
+      # 04-CONTEXT.md §"actor_resolver returning nil" locks the permissive
+      # contract; apps that need strict enforcement do it inside their own
+      # resolver lambda (`-> { Current.user || raise SomeAppError }`).
+      #
+      # Default nil (no resolver) means every version row's changed_by is
+      # nil. Apps wire this up by setting `c.actor_resolver = -> { ... }`
+      # in an initializer alongside `c.versioning = true`.
+      def actor_resolver
+        defined?(@actor_resolver) ? @actor_resolver : nil
+      end
+      attr_writer :actor_resolver # rubocop:disable Style/AccessorGrouping
+
+      # Public single-proc slot for value-change events.
+      # Signature: ->(value, change_type, context) { ... }
+      # - value:        TypedEAV::Value (the just-committed row)
+      # - change_type:  :create | :update | :destroy
+      # - context:      Hash (TypedEAV.current_context — frozen)
+      #
+      # Errors raised inside this proc are rescued by EventDispatcher and
+      # logged via Rails.logger.error — they do NOT propagate to the
+      # user's save call (the row is already committed). Internal subscribers
+      # (Phase 04 versioning, Phase 07 matview) fire BEFORE this proc and
+      # their errors DO propagate. See 03-CONTEXT.md §User-callback error policy.
+      #
+      # Reassignment after gem initialization does NOT disable internal
+      # subscribers — those live on EventDispatcher.value_change_internals,
+      # not here.
+      attr_accessor :on_value_change
 
-    # Callable returning the ambient scope (partition key) for class-level
-    # queries. Invoked by `TypedEAV.current_scope` when no explicit
-    # `scope:` kwarg is passed and no `with_scope` block is active.
-    config_accessor :scope_resolver, default: DEFAULT_SCOPE_RESOLVER
+      # Public single-proc slot for field-change events.
+      # Signature: ->(field, change_type) { ... }
+      # - field:        TypedEAV::Field::Base (or subclass)
+      # - change_type:  :create | :update | :destroy | :rename
+      #
+      # Note: TWO args, no context — asymmetric vs on_value_change by design.
+      # Field changes are CRUD-on-config (admin operations on field
+      # definitions), not per-entity user actions, so thread context is
+      # less relevant. The asymmetry is locked at 03-CONTEXT.md §Phase Boundary.
+      #
+      # :rename fires when `name` is among Field#saved_changes, even
+      # combined with other attr changes (sort_order, options, etc.) —
+      # Phase 07 matview needs the rename signal to regenerate column names
+      # even when the rename was bundled with other edits.
+      attr_accessor :on_field_change
 
-    # When true, class-level queries on a model that declared
-    # `has_typed_eav scope_method: ...` raise `TypedEAV::ScopeRequired`
-    # if no scope can be resolved (explicit arg, active `with_scope` block,
-    # or configured resolver all returned nil). Bypass per-call via
-    # `TypedEAV.unscoped { ... }`.
-    config_accessor :require_scope, default: true
+      # Phase 05 hook: fires from after_commit on TypedEAV::Value when a
+      # Field::Image-typed Value gains (or replaces) an attachment. Receives
+      # `(value, blob)`. Default nil — no-op when not configured.
+      #
+      # Hook ordering: fires AFTER versioning (Phase 04) and AFTER
+      # on_value_change (Phase 03). The hook is informational ("an image
+      # was attached"), not mutational; running it last avoids polluting
+      # earlier hooks' snapshots / context with attachment-derived state.
+      #
+      # Active Storage soft-detect (Gating Decision 1, Phase 05): when
+      # Active Storage is not loaded at engine boot, the after_commit
+      # dispatcher on TypedEAV::Value short-circuits via the
+      # `defined?(::ActiveStorage::Blob)` guard — this accessor exists
+      # regardless (set/get is a no-op if no dispatcher fires). Mirrors
+      # the on_value_change / on_field_change idiom (plain attr_accessor
+      # rather than the hand-rolled `defined?(@var)` reader because the
+      # hook contract is "nil means unset"; there is no "explicitly nil
+      # vs never set" distinction this hook needs to surface).
+      #
+      # File-attached has no parallel hook in Phase 05 — the on_image_attached
+      # name is image-specific by ROADMAP design. Apps that want a generic
+      # file-attached signal use on_value_change (Phase 03) or subscribe to
+      # ActiveSupport::Notifications directly.
+      attr_accessor :on_image_attached
 
-    class << self
       # Register a custom field type.
       def register_field_type(name, class_name)
         field_types[name.to_sym] = class_name
@@ -85,6 +259,28 @@ module TypedEAV
         self.field_types = BUILTIN_FIELD_TYPES.dup
         self.scope_resolver = DEFAULT_SCOPE_RESOLVER
         self.require_scope = true
+        # Phase 04 versioning master switch + actor resolver. Reset to defaults
+        # (false / nil) so test isolation matches `Config.on_value_change` / etc.
+        # Internal subscribers (TypedEAV::Versioning::Subscriber, registered
+        # at engine load by plan 04-02) are deliberately NOT cleared here —
+        # they live on EventDispatcher.value_change_internals and survive
+        # Config.reset! by design (the snapshot/restore split is locked at
+        # 03-CONTEXT.md §Reset split). Test teardown that needs to clear
+        # subscribers too calls EventDispatcher.reset!.
+        self.versioning = false
+        self.actor_resolver = nil
+        # Test isolation: scoping_spec/field_spec/etc. call Config.reset! in
+        # `after` hooks — this ensures user procs set in earlier tests don't
+        # leak across examples. Internal subscribers
+        # (EventDispatcher.value_change_internals/field_change_internals) are
+        # deliberately NOT reset here — they're populated at engine load by
+        # Phase 04+ and must persist across Config.reset!. Test teardown
+        # that needs to clear EVERYTHING calls EventDispatcher.reset! too.
+        self.on_value_change = nil
+        self.on_field_change = nil
+        # Phase 05 image-attached hook (parallel to on_value_change /
+        # on_field_change reset for test isolation).
+        self.on_image_attached = nil
       end
     end
   end

data/lib/typed_eav/csv_mapper.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module TypedEAV
+  # Pure stateless CSV-to-attributes transform.
+  #
+  # `TypedEAV::CSVMapper.row_to_attributes(row, mapping, fields_by_name: nil)`
+  # turns a single CSV row (`CSV::Row` for header-mapped files, or a plain
+  # `Array` for index-mapped headerless files) into a `Result` value object
+  # with `.attributes`, `.errors`, and `.success?` / `.failure?` predicates.
+  # Never raises on per-row content errors — cast failures land in `errors`,
+  # NOT in exceptions. The only ArgumentError path is mapping-shape
+  # validation, which fires before any row processing.
+  #
+  # ## Operating modes
+  #
+  # The 2-arg public form `row_to_attributes(row, mapping)` is the
+  # **passthrough mode**: raw cell values flow through unchanged keyed by
+  # the mapped field name. No coercion is attempted, no errors are possible.
+  # This honors the public 2-arg surface in CONTEXT line 13 + ROADMAP §Phase
+  # 6 success criterion exactly. Use this when the caller only needs CSV
+  # mapping (header → field-name) without typed coercion — e.g., when
+  # building a preview before the host record's partition is known.
+  #
+  # The 3-arg form `row_to_attributes(row, mapping, fields_by_name:
+  # defs_by_name)` is the **typed mode**: per-cell coercion runs through
+  # `field.cast(raw)` (the existing tuple contract documented on
+  # `TypedEAV::Field::Base#cast`). Cast failures (`invalid? == true`) land
+  # in `Result#errors` keyed by the field name, with the AR-symmetric
+  # message `"is invalid"`. Empty cells (nil / empty string) cast to nil
+  # per the `field.cast` contract and produce `attributes[name] = nil` with
+  # NO error. The caller is expected to pass the result of
+  # `record.class.typed_eav_definitions(scope:, parent_scope:).index_by(&:name)`
+  # (or equivalent) — the mapper has no record context and does not resolve
+  # fields itself.
+  #
+  # ## Mapping shape
+  #
+  # Single Hash. Keys are EITHER all `String` (CSV header names) OR all
+  # `Integer` (column indexes for headerless files). Mixed-key mappings
+  # raise `ArgumentError` immediately, before any row is touched, with a
+  # remediation message that tells the caller how to fix it.
+  #
+  # Mapping VALUES are field names — accepted as Symbol or String; the
+  # mapper coerces to String before lookup in `fields_by_name`. This
+  # matches the codebase convention where `field.name` is always a String.
+  #
+  # ## Unknown field in mapping (typed mode)
+  #
+  # When a mapping value (e.g. `:foo`) does NOT appear in `fields_by_name`,
+  # the cell is silently SKIPPED — it does NOT produce an error and does
+  # NOT appear in `Result#attributes`. Rationale: the mapper is a pure
+  # transform and has no record context. Mapping misconfiguration is a
+  # caller concern; callers that want to detect it can compare
+  # `result.attributes.keys` against the expected set. In passthrough mode
+  # there is no `fields_by_name` to look up against, so every mapped cell
+  # flows through unconditionally.
+  #
+  # ## Foundational principle
+  #
+  # NO HARDCODED ATTRIBUTE REFERENCES. The mapper resolves field metadata
+  # via the `fields_by_name:` keyword argument supplied by the caller —
+  # the mapper itself never inspects record attributes or partition state.
+  # Every field touch goes through `field.cast(raw)` which dispatches via
+  # the existing per-type cast contract.
+  module CSVMapper
+    # Plain value object — NOT an ActiveRecord model. No callbacks, no
+    # validations, no DB interaction. Two frozen Hashes; `success?` is just
+    # `errors.empty?`. Callers that need to combine multiple row Results
+    # into a batch view do so by composing the immutable Hashes in their
+    # own code (e.g., `results.flat_map(&:errors).reduce({}, :merge)`); the
+    # mapper does not provide a "merge" helper in v0.6.0.
+    class Result
+      attr_reader :attributes, :errors
+
+      def initialize(attributes:, errors:)
+        @attributes = attributes.freeze
+        @errors = errors.freeze
+      end
+
+      def success?
+        @errors.empty?
+      end
+
+      def failure?
+        !success?
+      end
+    end
+
+    class << self
+      # Transform a single row into a `Result`. See module-level docs for
+      # the full contract. Returns a `Result`; only raises on mapping-shape
+      # errors (mixed String + Integer keys).
+      def row_to_attributes(row, mapping, fields_by_name: nil)
+        validate_mapping_keys!(mapping)
+
+        attributes = {}
+        errors = {}
+
+        mapping.each do |source_key, raw_field_name|
+          # Unified cell read: both `CSV::Row#[String]` and `Array#[Integer]`
+          # work via `[]` — homogeneous key validation above ensures
+          # `source_key` matches the row representation (header name vs
+          # index).
+          raw_cell = row[source_key]
+
+          # Codebase convention: field names are always Strings on the AR
+          # side. Mapping values may be Symbol or String — coerce here so
+          # the lookup against `fields_by_name` and the keys in
+          # `attributes` / `errors` are consistent regardless of caller
+          # input style.
+          name = raw_field_name.to_s
+
+          if fields_by_name.nil?
+            # Passthrough mode — no coercion, no errors possible. Honors
+            # the 2-arg public surface in CONTEXT line 13 + ROADMAP §Phase
+            # 6. Cell flows through unchanged.
+            attributes[name] = raw_cell
+          else
+            # Typed mode — silently skip unknown fields (see module docs).
+            field = fields_by_name[name]
+            next if field.nil?
+
+            casted, invalid = field.cast(raw_cell)
+            if invalid
+              # AR-symmetric message; matches `errors_by_record` in the
+              # bulk-write surface and `errors.add(:value, :invalid)` in
+              # `Value#validate_value`. Plain Hash with String keys per
+              # RESEARCH §Open-Question Resolutions §errors_hash shape.
+              (errors[name] ||= []) << "is invalid"
+            else
+              attributes[name] = casted
+            end
+          end
+        end
+
+        Result.new(attributes: attributes, errors: errors)
+      end
+
+      private
+
+      # Mapping-shape validation: keys must be all-String OR all-Integer.
+      # Mixed keys raise immediately, BEFORE any row processing — fail
+      # fast on configuration errors so the caller catches them on the
+      # first invocation rather than silently producing partial Results.
+      def validate_mapping_keys!(mapping)
+        key_classes = mapping.keys.map(&:class).uniq
+        return if key_classes == [String] || key_classes == [Integer] || key_classes.empty?
+
+        raise ArgumentError,
+              "CSVMapper mapping must use either all String keys (CSV headers) " \
+              "or all Integer keys (column indexes), not both. " \
+              "Got: #{mapping.inspect}"
+      end
+    end
+  end
+end

data/lib/typed_eav/currency_storage_contract.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Storage contract for Field::Currency's two-cell value shape.
+  class CurrencyStorageContract < FieldStorageContract
+    VALUE_COLUMNS = %i[decimal_value string_value].freeze
+    AMOUNT_COLUMN = :decimal_value
+    CURRENCY_COLUMN = :string_value
+
+    def self.value_columns
+      VALUE_COLUMNS
+    end
+
+    def self.query_column(operator)
+      operator == :currency_eq ? CURRENCY_COLUMN : AMOUNT_COLUMN
+    end
+
+    delegate :value_columns, :query_column, to: :class
+
+    def read(value_record)
+      amount = value_record[AMOUNT_COLUMN]
+      currency = value_record[CURRENCY_COLUMN]
+      return nil if amount.nil? && currency.nil?
+
+      { amount: amount, currency: currency }
+    end
+
+    def write(value_record, casted)
+      if casted.nil?
+        value_record[AMOUNT_COLUMN] = nil
+        value_record[CURRENCY_COLUMN] = nil
+      else
+        value_record[AMOUNT_COLUMN] = casted[:amount]
+        value_record[CURRENCY_COLUMN] = casted[:currency]
+      end
+    end
+
+    def apply_default(value_record)
+      default = field.default_value
+      return unless default.is_a?(Hash)
+
+      value_record[AMOUNT_COLUMN] = default[:amount] || default["amount"]
+      value_record[CURRENCY_COLUMN] = default[:currency] || default["currency"]
+    end
+  end
+end

data/lib/typed_eav/engine.rb

@@ -8,6 +8,13 @@ module TypedEAV
       require_relative "column_mapping"
       require_relative "config"
       require_relative "registry"
+      # Eager-loaded (not autoloaded) — Phase 04 versioning will register on
+      # EventDispatcher at engine boot, before any model reference triggers
+      # autoload. Without this require_relative, Phase 04's engine-time
+      # `register_internal_value_change` call would const-resolve the module
+      # for the first time and run a fresh `@value_change_internals = []`
+      # AFTER versioning had already pushed onto a different instance.
+      require_relative "event_dispatcher"
     end
 
     # Make `has_typed_eav` available on all ActiveRecord models
@@ -16,5 +23,115 @@ module TypedEAV
         include TypedEAV::HasTypedEAV
       end
     end
+
+    # Phase 04 versioning subscriber registration.
+    #
+    # CONDITIONAL on TypedEAV.config.versioning. When false (the default
+    # for apps that don't enable versioning), no subscriber is registered:
+    # zero callable in EventDispatcher.value_change_internals, zero per-write
+    # dispatch overhead, zero config reads on the hot path. This is the
+    # locked CONTEXT contract — line 17 says "zero overhead for apps that
+    # don't use versioning", which means literally no callable, not "callable
+    # that early-returns".
+    #
+    # We use `config.after_initialize` rather than a Rails `initializer` block
+    # because we need to consult host-set config values. The host's
+    # `config/initializers/typed_eav.rb` runs AFTER all engine initializers
+    # but BEFORE `config.after_initialize`. By the time this block fires,
+    # `TypedEAV.config.versioning` reflects the host's chosen value (or the
+    # default `false` if the host never touched it).
+    #
+    # Trade-off (documented in 04-02-PLAN §Plan-time decisions §6): apps
+    # that toggle `c.versioning = true` at runtime AFTER `after_initialize`
+    # has fired (e.g., a Rails console session that monkey-patches Config,
+    # or a feature-flag flip mid-process) will NOT get versioning until
+    # process restart. Runtime toggle is not a documented use case — adding
+    # a register/deregister API is out of scope for Phase 04. The Risk §1
+    # late-toggle concern from RESEARCH is acceptably narrowed by this
+    # trade-off.
+    #
+    # Slot 0 ordering: Phase 07 (future matview) will register its
+    # subscriber via its own `config.after_initialize` block declared LATER
+    # in this same engine file. Rails runs `after_initialize` blocks in
+    # declaration order within a single Engine class, so versioning's block
+    # fires first → slot 0. The regression spec (plan 04-03 P03) is the
+    # ongoing guard.
+    #
+    # Why a one-line callable to a class method (not inline registration):
+    # `TypedEAV::Versioning.register_if_enabled` is the testable seam. The
+    # slot-0 regression spec (plan 04-03 P03) and the zero-overhead
+    # verification spec (this plan, subscriber_spec) cannot reboot the Rails
+    # process inside RSpec — but they CAN call the helper directly against
+    # a fresh internals array to exercise both branches (versioning on/off)
+    # in-process. Inlining the `if` here would force tests to either reboot
+    # the engine or use brittle private-block extraction.
+    config.after_initialize do
+      TypedEAV::Versioning.register_if_enabled
+    end
+
+    # Phase 05 Active Storage soft-detect (Gating Decision 1).
+    #
+    # Mirrors the acts_as_tenant precedent (Config::DEFAULT_SCOPE_RESOLVER
+    # in lib/typed_eav/config.rb lines 49-53): the gem detects without
+    # requiring. When ActiveStorage::Blob is not defined at this point in
+    # boot, has_one_attached is NOT registered on TypedEAV::Value — apps
+    # that don't use Image/File field types pay zero overhead, AND the
+    # gemspec stays free of an activestorage hard-dependency.
+    #
+    # When AS IS loaded (Rails 7.1+ with the rails meta-gem, or an
+    # explicit `gem 'activestorage'` line), TypedEAV::Value gains a
+    # single :attachment has_one_attached association that covers BOTH
+    # Field::Image and Field::File typed Values. The Image vs File
+    # distinction at runtime is `value.field.is_a?(Field::Image)` (used
+    # by the on_image_attached dispatcher on TypedEAV::Value); the blob's
+    # content_type is the source of truth for image-vs-other-file at
+    # render time.
+    #
+    # Why a single shared association (not :image_attachment +
+    # :file_attachment): TypedEAV::Value is a monolithic table — every
+    # Value row gets every association declared on the class. Two
+    # associations would double the AR association overhead on every
+    # Value row (Text, Integer, etc.), even when no attachment is in
+    # play. RESEARCH §Risk 3 documents this rationale.
+    #
+    # Second after_initialize block (versioning's is the first): Rails
+    # runs after_initialize blocks in declaration order within a single
+    # Engine class. Versioning's slot-0 dispatcher position at the
+    # EventDispatcher level is preserved (dispatcher slots are an
+    # EventDispatcher-internal concern; the engine's after_initialize
+    # ordering is independent). Phase 07 matview will append its own
+    # block after this one.
+    #
+    # Why a one-line callable to a class method (testable seam): the
+    # active_storage_soft_detect_spec cannot reboot Rails inside RSpec
+    # to exercise both branches. By extracting the body into
+    # `Engine.register_attachment_associations!`, specs call the helper
+    # directly with whatever ::ActiveStorage state they need to test.
+    # Pattern matches Phase 04's `Versioning.register_if_enabled`.
+    config.after_initialize do
+      TypedEAV::Engine.register_attachment_associations!
+    end
+
+    # Conditionally register the :attachment has_one_attached association
+    # on TypedEAV::Value. Idempotent — safe to call multiple times. The
+    # idempotency guard (`@attachment_registered`) prevents double-
+    # registration when specs invoke the seam in addition to the engine
+    # boot path. Without the guard, AR's has_one_attached macro would
+    # redefine the association methods (technically harmless but
+    # generates RuntimeError noise on duplicate declaration in newer AS
+    # versions).
+    #
+    # Returns truthy on first successful registration, falsy when AS is
+    # unloaded or the association is already registered. The return is
+    # not part of the public contract — specs that care about the
+    # registration outcome inspect TypedEAV::Value.reflect_on_attachment
+    # directly.
+    def self.register_attachment_associations!
+      return false unless defined?(::ActiveStorage::Blob)
+      return false if @attachment_registered
+
+      TypedEAV::Value.has_one_attached :attachment
+      @attachment_registered = true
+    end
   end
 end