typed_eav 0.2.1 → 0.3.1

data/app/models/typed_eav/field/range_bounded.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module Field
+    # Intermediate STI base for field families that constrain a single
+    # comparable value by `min`/`max` bounds.
+    #
+    # Leaves: `Field::Integer`, `Field::Decimal`, `Field::Date`,
+    # `Field::DateTime`. `Field::Percentage` keeps its `< Decimal` chain
+    # (so the new full chain is
+    # `Percentage < Decimal < RangeBounded < Base`).
+    #
+    # Does NOT declare a `value_column` — each leaf still owns its typed
+    # column (`integer_value`, `decimal_value`, `date_value`,
+    # `datetime_value`). The family is identified by "has min/max bounds",
+    # not by storage shape.
+    #
+    # Hoists the protected `validate_range` / `validate_date_range` /
+    # `validate_datetime_range` helpers previously kept on `Field::Base`.
+    # Each leaf declares its own `store_accessor` (`:min`/`:max` for
+    # Integer/Decimal; `:min_date`/`:max_date` for Date;
+    # `:min_datetime`/`:max_datetime` for DateTime) and its own
+    # `validates :max, comparison: { greater_than_or_equal_to: :min }`
+    # macro using the appropriate key names. Adding the macro to
+    # Date/DateTime in-slice closes a latent-bug gap previously only
+    # caught on Integer/Decimal.
+    #
+    # Public extension point: external authors can subclass this directly
+    # if they want a typed numeric/temporal column with min/max guards
+    # (see README §"Custom field types"). STI dispatch is unaffected.
+    class RangeBounded < Base
+      protected
+
+      def validate_range(record, val)
+        opts = options_hash
+        record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min]) if opts[:min] && val < opts[:min].to_d
+        return unless opts[:max] && val > opts[:max].to_d
+
+        record.errors.add(:value, :less_than_or_equal_to, count: opts[:max])
+      end
+
+      def validate_date_range(record, val)
+        opts = options_hash
+        if opts[:min_date]
+          min = ::Date.parse(opts[:min_date])
+          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_date]) if val < min
+        end
+        if opts[:max_date]
+          max = ::Date.parse(opts[:max_date])
+          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_date]) if val > max
+        end
+      rescue ::Date::Error
+        record.errors.add(:base, "field has invalid date configuration")
+      end
+
+      def validate_datetime_range(record, val)
+        opts = options_hash
+        if opts[:min_datetime]
+          min = ::Time.zone.parse(opts[:min_datetime])
+          record.errors.add(:value, :greater_than_or_equal_to, count: opts[:min_datetime]) if val < min
+        end
+        if opts[:max_datetime]
+          max = ::Time.zone.parse(opts[:max_datetime])
+          record.errors.add(:value, :less_than_or_equal_to, count: opts[:max_datetime]) if val > max
+        end
+      rescue ArgumentError
+        record.errors.add(:base, "field has invalid datetime configuration")
+      end
+    end
+  end
+end

data/app/models/typed_eav/field/select.rb

@@ -2,20 +2,19 @@
 
 module TypedEAV
   module Field
+    # Single-choice option-set field. Stores the chosen value in
+    # `string_value`. Inherits `optionable? = true`, the public-facing
+    # sorted `allowed_values` helper, and the protected
+    # `validate_option_inclusion` helper from `Field::Optionable`. Stays a
+    # direct child of `Field::Base` — Optionable is a concern (mixin), not
+    # an intermediate STI class, because Select and MultiSelect don't
+    # share a `value_column`.
     class Select < Base
+      include Optionable
+
       value_column :string_value
       operators :eq, :not_eq, :is_null, :is_not_null
 
-      def optionable? = true
-
-      def allowed_values
-        if field_options.loaded?
-          field_options.sort_by { |o| [o.sort_order || 0, o.label.to_s] }.map(&:value)
-        else
-          field_options.sorted.pluck(:value)
-        end
-      end
-
       def cast(raw)
         [raw&.to_s, false]
       end

data/app/models/typed_eav/field/text.rb

@@ -2,40 +2,22 @@
 
 module TypedEAV
   module Field
-    class Text < Base
+    # String-typed field with optional length / pattern guards. Storage,
+    # `store_accessor`, numericality validators, `max_gte_min_length`,
+    # `validate_pattern_syntax`, and the default `validate_typed_value`
+    # (length + pattern) all come from `Field::ValidatedString`. Text adds
+    # only `cast` (raw → String).
+    class Text < ValidatedString
+      # Re-declare value_column to populate Text's own @value_columns class
+      # instance variable — Ruby class ivars are NOT inherited through
+      # subclass lookup (the same workaround `Field::Percentage` uses
+      # against `Field::Decimal`). BC-safe and explicit; STI dispatch is
+      # unaffected (the `type` column still stores "TypedEAV::Field::Text").
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-
-      validates :min_length, numericality: { only_integer: true, greater_than_or_equal_to: 0 }, allow_nil: true
-      validates :max_length, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
-      validate :max_gte_min_length
-      validate :validate_pattern_syntax
-
       def cast(raw)
         [raw&.to_s, false]
       end
-
-      def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
-      end
-
-      private
-
-      def max_gte_min_length
-        return unless min_length && max_length
-
-        errors.add(:max_length, "must be >= min_length") if max_length < min_length
-      end
-
-      def validate_pattern_syntax
-        return if pattern.blank?
-
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        errors.add(:pattern, "is invalid: #{e.message}")
-      end
     end
   end
 end

data/app/models/typed_eav/field/url.rb

@@ -4,12 +4,21 @@ require "uri"
 
 module TypedEAV
   module Field
-    class Url < Base
+    # URL-typed field. Inherits `string_value` storage shape, the
+    # `min_length` / `max_length` / `pattern` `store_accessor`, the
+    # `max_gte_min_length` guard, and the `validate_pattern_syntax` guard
+    # from `Field::ValidatedString`. Adds the `URL_FORMAT` regex
+    # (http/https only) and layers the format check onto
+    # `validate_typed_value` via `super`.
+    #
+    # Latent-bug fix (per ADR-0004): `max_gte_min_length` (previously
+    # only on Text) now applies here — a Url field configured with
+    # `max_length < min_length` fails at field-save.
+    class Url < ValidatedString
+      # Re-declare value_column for Ruby class-ivar non-inheritance — see
+      # comment on Field::Text. STI dispatch is unaffected.
       value_column :string_value
 
-      store_accessor :options, :min_length, :max_length, :pattern
-      validate :validate_pattern_syntax
-
       URL_FORMAT = /\A#{URI::DEFAULT_PARSER.make_regexp(%w[http https])}\z/
 
       def cast(raw)
@@ -21,20 +30,9 @@ module TypedEAV
       end
 
       def validate_typed_value(record, val)
-        validate_length(record, val)
-        validate_pattern(record, val) if pattern.present?
+        super
         record.errors.add(:value, "is not a valid URL") unless url_format_valid?(val)
       end
-
-      private
-
-      def validate_pattern_syntax
-        return if pattern.blank?
-
-        Regexp.new(pattern)
-      rescue RegexpError => e
-        errors.add(:pattern, "is invalid: #{e.message}")
-      end
     end
   end
 end

data/app/models/typed_eav/field/validated_string.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module TypedEAV
+  module Field
+    # Intermediate STI base for string-valued field families that share a
+    # `min_length` / `max_length` / `pattern` validation surface.
+    #
+    # Leaves: `Field::Text`, `Field::Email`, `Field::Url`.
+    #
+    # Hoists the `string_value` storage declaration, the
+    # `store_accessor :options, :min_length, :max_length, :pattern` line,
+    # the `min_length` / `max_length` numericality validators, the
+    # `max_gte_min_length` guard, the `validate_pattern_syntax` guard, and
+    # the protected `validate_length` / `validate_pattern` helpers — all
+    # previously duplicated across Text/Email/Url with one drift gap
+    # (`max_gte_min_length` was only on Text).
+    #
+    # Default `validate_typed_value` runs `validate_length` plus
+    # `validate_pattern if pattern.present?`. Leaves override and call
+    # `super` to layer on their format-specific check (Email's
+    # `EMAIL_FORMAT`, Url's `URL_FORMAT`).
+    #
+    # Public extension point: external authors can subclass this directly
+    # to inherit the full min/max/pattern surface (see README §"Custom field
+    # types"). STI dispatch is unaffected — leaves still store their own
+    # class names in the `type` column.
+    class ValidatedString < Base
+      value_column :string_value
+
+      store_accessor :options, :min_length, :max_length, :pattern
+
+      validates :min_length, numericality: { only_integer: true, greater_than_or_equal_to: 0 }, allow_nil: true
+      validates :max_length, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
+      validate :max_gte_min_length
+      validate :validate_pattern_syntax
+
+      def validate_typed_value(record, val)
+        validate_length(record, val)
+        validate_pattern(record, val) if pattern.present?
+      end
+
+      protected
+
+      def validate_length(record, val)
+        opts = options_hash
+        str = val.to_s
+        if opts[:min_length] && str.length < opts[:min_length].to_i
+          record.errors.add(:value, :too_short, count: opts[:min_length])
+        end
+        return unless opts[:max_length] && str.length > opts[:max_length].to_i
+
+        record.errors.add(:value, :too_long, count: opts[:max_length])
+      end
+
+      def validate_pattern(record, val)
+        opts = options_hash
+        pattern = opts[:pattern]
+        return if pattern.blank?
+
+        matched = Timeout.timeout(1) { Regexp.new(pattern).match?(val.to_s) }
+        record.errors.add(:value, :invalid) unless matched
+      rescue RegexpError
+        record.errors.add(:value, "has an invalid pattern configured")
+      rescue Timeout::Error
+        record.errors.add(:value, "pattern validation timed out")
+      end
+
+      private
+
+      def max_gte_min_length
+        return unless min_length && max_length
+
+        errors.add(:max_length, "must be >= min_length") if max_length < min_length
+      end
+
+      def validate_pattern_syntax
+        return if pattern.blank?
+
+        Regexp.new(pattern)
+      rescue RegexpError => e
+        errors.add(:pattern, "is invalid: #{e.message}")
+      end
+    end
+  end
+end

data/app/models/typed_eav/value.rb

@@ -86,7 +86,7 @@ module TypedEAV
     def value
       return nil unless field
 
-      field.storage_contract.read(self)
+      field.read_value(self)
     end
 
     def value=(val)
@@ -114,7 +114,7 @@ module TypedEAV
         # decimal_value, raising TypeMismatch at save time.
         # Rails will further cast each column on save via its column type.
         casted, invalid = field.cast(val)
-        field.storage_contract.write(self, casted)
+        field.write_value(self, casted)
         @cast_was_invalid = invalid
       else
         # Field not yet assigned - stash for later
@@ -276,7 +276,7 @@ module TypedEAV
       #      Currency in Phase 05). Reconstructing that shape from
       #      before_value's per-column hash adds complexity for zero benefit
       #      since the per-column values are exactly what we need.
-      field.storage_contract.value_columns.each do |col|
+      field.class.value_columns.each do |col|
         self[col] = version.before_value[col.to_s]
       end
 
@@ -369,20 +369,20 @@ module TypedEAV
     end
 
     # Writes the field's configured default to the typed column(s) via the
-    # `field.apply_default_to(self)` dispatch. Does NOT route through value=
+    # `field.apply_default(self)` dispatch. Does NOT route through value=
     # because field.default_value is already cast via
     # cast(default_value_meta["v"]).first — re-casting would be redundant.
     # Field-side validate_default_value (field/base.rb) catches invalid raw
-    # defaults at field save time, so what apply_default_to writes is always
+    # defaults at field save time, so what apply_default writes is always
     # either a castable value or nil.
     #
     # Multi-cell forward-compat: single-cell types fall through to
-    # `self[value_column] = field.default_value` (Field::Base default).
-    # Currency / future multi-cell types override `apply_default_to` to
+    # `self[value_columns.first] = field.default_value` (TypedStorage default).
+    # Currency / future multi-cell types override `apply_default` to
     # populate multiple columns from a composite default. The dispatch
     # preserves the bypass-Value#value= contract end-to-end.
     def apply_field_default
-      field.storage_contract.apply_default(self)
+      field.apply_default(self)
     end
 
     def validate_value
@@ -540,7 +540,7 @@ module TypedEAV
       # code) cell would silently be missed by the dispatch gate, and
       # Phase 04 versioning would never see it (Scout §3 / Discrepancy D3
       # from plan 04-01).
-      return unless field.storage_contract.changed?(self)
+      return unless field.value_changed?(self)
 
       TypedEAV::EventDispatcher.dispatch_value_change(self, :update)
     end

data/lib/typed_eav/bulk_read.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Bulk-read query object. Returns `{ record_id => { field_name => value } }`
+  # for an Enumerable of host records — the class-method bulk variant of
+  # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
+  # record count or field count.
+  #
+  # ## Pipeline (one query per unique partition tuple + one bulk value preload)
+  #
+  #   1. validate_records!    — nil -> ArgumentError; single-class invariant
+  #   2. group_by_tuple       — `[typed_eav_scope, typed_eav_parent_scope]`
+  #   3. winning_ids_by_tuple — `typed_eav_definitions` per unique tuple via
+  #                             `Partition.definitions_by_name` (shared
+  #                             collision-precedence helper)
+  #   4. preload_values       — single SELECT across ALL records
+  #   5. build_result_hash    — per-record inner hash; orphan-skip + winning-id
+  #                             precedence mirrored from the instance path.
+  #
+  # ## Query bound
+  #
+  #   - 1 SELECT typed_eav_values WHERE entity_type=? AND entity_id IN (?)
+  #   - 1 SELECT typed_eav_fields WHERE id IN (?)           (via includes)
+  #   - 1 SELECT typed_eav_fields per unique partition tuple
+  #
+  # Total: 2 + (unique partition tuples) queries — independent of record count.
+  #
+  # ## Single-class invariant
+  #
+  # The polymorphic value query (`entity_type: host_class.name`) targets ONE
+  # class; mixed-class input would silently miss rows of the other class. STI
+  # subclasses pass via `records.all?(host_class)`.
+  class BulkRead
+    def initialize(host_class:, records:)
+      @host_class = host_class
+      @records    = records
+    end
+
+    def to_hash
+      records = coerce_records
+      return {} if records.empty?
+
+      validate_record_classes!(records)
+
+      tuples_by_record = group_by_tuple(records)
+      winning_ids_by_tuple = winning_ids_by_tuple(tuples_by_record.values.uniq)
+      values_by_record_id = preload_values(records)
+
+      build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+    end
+
+    private
+
+    attr_reader :host_class
+
+    def coerce_records
+      raise ArgumentError, "typed_eav_hash_for requires an Enumerable of records, got nil" if @records.nil?
+
+      @records.to_a
+    end
+
+    def validate_record_classes!(records)
+      return if records.all?(host_class)
+
+      classes = records.map { |r| r.class.name }.uniq
+      raise ArgumentError,
+            "typed_eav_hash_for expects records of class #{host_class.name} (or its subclasses); " \
+            "got mixed classes: #{classes.join(", ")}"
+    end
+
+    def group_by_tuple(records)
+      # Memo of record -> tuple key so each record only computes its tuple once.
+      records.index_with { |r| [r.typed_eav_scope, r.typed_eav_parent_scope] }
+    end
+
+    def winning_ids_by_tuple(tuples)
+      tuples.each_with_object({}) do |(s, ps), memo|
+        defs = host_class.typed_eav_definitions(scope: s, parent_scope: ps)
+        memo[[s, ps]] = TypedEAV::Partition.definitions_by_name(defs).transform_values(&:id)
+      end
+    end
+
+    def preload_values(records)
+      rows = TypedEAV::Value
+             .includes(:field)
+             .where(entity_type: host_class.name, entity_id: records.map(&:id))
+             .to_a
+      rows.group_by(&:entity_id)
+    end
+
+    def build_result(records, tuples_by_record, winning_ids_by_tuple, values_by_record_id)
+      records.each_with_object({}) do |record, result|
+        tuple_key            = tuples_by_record[record]
+        winning_ids_by_name  = winning_ids_by_tuple.fetch(tuple_key, {})
+        rows                 = values_by_record_id.fetch(record.id, [])
+        result[record.id]    = inner_hash_for(rows, winning_ids_by_name)
+      end
+    end
+
+    # Builds the inner `{ field_name => value }` hash for a single record.
+    #
+    # Skips orphans (`tv.field` nil — definition deleted via raw SQL or a
+    # Phase 02 `:nullify` cascade). When a winning field_id is registered
+    # for the name, only its row may surface (scoped-beats-global collision
+    # precedence). When no winner is registered (definition deleted while
+    # values remain), fall back to first-wins so the hash isn't lossy.
+    def inner_hash_for(value_rows, winning_ids_by_name)
+      value_rows.each_with_object({}) do |tv, inner|
+        next unless tv.field
+
+        name = tv.field.name
+        winning_id = winning_ids_by_name[name]
+        next assign_with_precedence(inner, name, tv, winning_id) if winning_id
+
+        inner[name] = tv.value unless inner.key?(name)
+      end
+    end
+
+    def assign_with_precedence(inner, name, value_row, winning_id)
+      effective_id = value_row.field_id || value_row.field&.id
+      inner[name] = value_row.value if effective_id == winning_id
+    end
+  end
+end

data/lib/typed_eav/engine.rb

@@ -5,7 +5,7 @@ module TypedEAV
     isolate_namespace TypedEAV
 
     initializer "typed_eav.autoload" do
-      require_relative "column_mapping"
+      require_relative "field/typed_storage"
       require_relative "config"
       require_relative "registry"
       # Eager-loaded (not autoloaded) — Phase 04 versioning will register on

data/lib/typed_eav/entity_query.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Class-level query orchestration extended onto host AR models by the
+  # `has_typed_eav` macro. Owns the `UNSET_SCOPE` / `ALL_SCOPES` sentinels
+  # and the `resolve_scope` chain; delegates the heavy lifting to
+  # `FilterQuery` (multi-filter SQL composition) and `BulkRead` (bulk
+  # per-record reads). `bulk_set_typed_eav_values` stays as a 3-line wrapper
+  # around the existing `BulkWrite` executor.
+  module EntityQuery
+    # Sentinel for the `scope:` kwarg default. Distinguishes "kwarg not
+    # passed -> resolve from ambient" (UNSET_SCOPE) from "explicitly nil ->
+    # filter to global-only fields" (preserves prior behavior).
+    UNSET_SCOPE = Object.new.freeze
+
+    # Sentinel returned by `resolve_scope` inside an `unscoped { }` block.
+    # Signals the caller to skip the scope filter entirely (return fields
+    # across all partitions, not just global).
+    ALL_SCOPES = Object.new.freeze
+
+    # Query by custom field values. Accepts an array of filter hashes
+    # or a hash of hashes (from form params).
+    #
+    # Each filter needs:
+    #   :name or :n      - the field name
+    #   :op or :operator - the operator (default: :eq)
+    #   :value or :v     - the comparison value
+    #
+    #   Contact.where_typed_eav(
+    #     { name: "age", op: :gt, value: 21 },
+    #     { name: "city", value: "Portland" }   # op defaults to :eq
+    #   )
+    #
+    # `scope:` and `parent_scope:` behavior:
+    #   - omitted        -> resolve from ambient (`with_scope` -> resolver -> raise/nil)
+    #   - passed a value -> use verbatim (explicit override; admin/test path)
+    #   - passed nil     -> filter to global-only on that axis (prior behavior)
+    def where_typed_eav(*filters, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      effective_scope, effective_parent = scope_pair(resolved)
+
+      TypedEAV::FilterQuery.new(
+        model: self,
+        filters: filters,
+        scope: effective_scope,
+        parent_scope: effective_parent,
+      ).to_relation
+    end
+
+    # Shorthand for single-field queries.
+    #
+    #   Contact.with_field("age", :gt, 21)
+    #   Contact.with_field("active", true)      # op defaults to :eq
+    #   Contact.with_field("name", :contains, "smith")
+    #
+    # Accepts both `scope:` and `parent_scope:` kwargs with the same
+    # ambient/explicit/nil semantics as `where_typed_eav`. Single-scope
+    # callers (no `parent_scope:`) are unaffected.
+    def with_field(name, operator_or_value = nil, value = nil, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      filter = if value.nil? && !operator_or_value.is_a?(Symbol)
+                 # Two-arg form: with_field("name", "value") implies :eq
+                 { name: name, op: :eq, value: operator_or_value }
+               else
+                 { name: name, op: operator_or_value, value: value }
+               end
+      where_typed_eav(filter, scope: scope, parent_scope: parent_scope)
+    end
+
+    # Returns field definitions for this entity type.
+    #
+    # `scope:` and `parent_scope:` behavior:
+    #   - omitted        -> resolve from ambient (`with_scope` -> resolver -> raise/nil)
+    #   - passed a value -> use verbatim (explicit override; admin/test path)
+    #   - passed nil     -> filter to global-only on that axis (prior behavior preserved)
+    def typed_eav_definitions(scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
+      resolved = resolve_scope(scope, parent_scope)
+      if resolved.equal?(ALL_SCOPES)
+        TypedEAV::Partition.visible_fields(entity_type: name, mode: :all_partitions)
+      else
+        s, ps = resolved
+        TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
+      end
+    end
+
+    # Bulk read API. Returns `{ record_id => { field_name => value } }` for
+    # an Enumerable of host records — the class-method bulk variant of
+    # `HasTypedEAV::InstanceMethods#typed_eav_hash`. N+1-free regardless of
+    # record count or field count. See `TypedEAV::BulkRead` for the pipeline
+    # and query bound.
+    def typed_eav_hash_for(records)
+      TypedEAV::BulkRead.new(host_class: self, records: records).to_hash
+    end
+
+    # Bulk write API. Sets the same `values_by_field_name` Hash on every
+    # record in `records` inside ONE outer ActiveRecord transaction with a
+    # SAVEPOINT-PER-RECORD failure-isolation envelope. See `TypedEAV::BulkWrite`
+    # for the transaction shape, error-aggregation contract, and the
+    # `version_grouping:` semantics.
+    def bulk_set_typed_eav_values(records, values_by_field_name, version_grouping: :default)
+      TypedEAV::BulkWrite.execute(
+        host_class: self,
+        records: records,
+        values_by_field_name: values_by_field_name,
+        version_grouping: version_grouping,
+      )
+    end
+
+    private
+
+    # Translates a resolved scope into the `(scope, parent_scope)` pair
+    # passed to `FilterQuery`. Preserves the `ALL_SCOPES` sentinel through
+    # to `FilterQuery` (it routes to the multimap branch); for resolved
+    # tuples, returns the pair verbatim.
+    def scope_pair(resolved)
+      return [ALL_SCOPES, nil] if resolved.equal?(ALL_SCOPES)
+
+      resolved
+    end
+
+    # Resolves the scope and parent_scope kwargs into a concrete tuple for
+    # field-definition lookup. Returns one of:
+    #   - `ALL_SCOPES`            — inside `TypedEAV.unscoped { }`, atomic bypass.
+    #   - `[scope, parent_scope]` — both elements are String or nil.
+    # Raises:
+    #   - `TypedEAV::ScopeRequired` when the model declares `scope_method:`
+    #     but ambient scope can't be resolved and `require_scope` is true.
+    def resolve_scope(explicit_scope, explicit_parent_scope)
+      return ALL_SCOPES if TypedEAV.unscoped?
+
+      if explicit_given?(explicit_scope, explicit_parent_scope)
+        return resolve_explicit_scope(explicit_scope, explicit_parent_scope)
+      end
+
+      return [nil, nil] unless typed_eav_scope_method
+
+      resolve_ambient_scope
+    end
+
+    def explicit_given?(explicit_scope, explicit_parent_scope)
+      !explicit_scope.equal?(UNSET_SCOPE) || !explicit_parent_scope.equal?(UNSET_SCOPE)
+    end
+
+    # Per-slot normalize via `ScopeTuple.normalize_permissive` to coerce
+    # scalars/AR-records to strings, with UNSET_SCOPE collapsing to nil for
+    # the corresponding slot. Orphan-parent invariant: a request for
+    # parent_scope without scope is dead-letter — silently narrow ps to nil.
+    def resolve_explicit_scope(explicit_scope, explicit_parent_scope)
+      s = normalize_explicit_or_nil(explicit_scope, slot: :scope)
+      ps = normalize_explicit_or_nil(explicit_parent_scope, slot: :parent)
+      ps = nil unless TypedEAV::ScopeTuple.invariant_satisfied?(s, ps)
+      [s, ps]
+    end
+
+    def normalize_explicit_or_nil(value, slot:)
+      return nil if value.equal?(UNSET_SCOPE)
+
+      normalize_explicit_slot(value, slot: slot)
+    end
+
+    def normalize_explicit_slot(value, slot:)
+      tuple = slot == :scope ? [value, nil] : [nil, value]
+      index = slot == :scope ? :first : :last
+      TypedEAV::ScopeTuple.normalize_permissive(tuple)&.public_send(index)
+    end
+
+    # Ambient resolver path (via `with_scope` stack or configured lambda).
+    # `TypedEAV.current_scope` already validates the return shape to
+    # `nil | [a, b]` — no shape check is duplicated here.
+    def resolve_ambient_scope
+      resolved = TypedEAV.current_scope
+      return resolved if resolved
+
+      raise_scope_required if TypedEAV.config.require_scope
+
+      [nil, nil]
+    end
+
+    def raise_scope_required
+      raise TypedEAV::ScopeRequired,
+            "No ambient scope resolvable for #{name}. " \
+            "Wrap the call in `TypedEAV.with_scope(value) { ... }`, " \
+            "configure `TypedEAV.config.scope_resolver`, or use " \
+            "`TypedEAV.unscoped { ... }` to deliberately bypass."
+    end
+  end
+end