typed_eav 0.1.0 → 0.2.0

data/lib/typed_eav/has_typed_eav.rb

@@ -31,15 +31,33 @@ module TypedEAV
   module HasTypedEAV
     extend ActiveSupport::Concern
 
-    # Indexes field definitions by name with deterministic collision
-    # resolution: when a global (scope=NULL) and a scoped field share a
-    # name, the scoped row wins. `for_entity(name, scope:)` returns both
-    # rows on a collision, and a bare `index_by(&:name)` would let DB row
-    # order pick the winner. Shared by the class-query path
+    # Indexes field definitions by name with deterministic three-way
+    # collision resolution: when global (scope=NULL, parent_scope=NULL),
+    # scope-only (scope set, parent_scope=NULL), and full-triple (both set)
+    # fields share a name, the most-specific row wins.
+    #
+    # Sort key `[scope.nil? ? 0 : 1, parent_scope.nil? ? 0 : 1]` orders rows:
+    #   [0, 0] global              (least specific) → comes first
+    #   [1, 0] scope-only          (middle)
+    #   [1, 1] full triple         (most specific)  → comes last
+    #
+    # `index_by(&:name)` keeps the LAST entry on duplicate keys (Rails
+    # convention via `Array#to_h`), so most-specific wins. The two-key sort
+    # extends the prior "scoped beats global" rule into "two-key beats
+    # one-key beats global" without changing the index_by-last-wins
+    # mechanism. The `(scope=NULL, parent_scope=NOT NULL)` slot is unreachable
+    # by construction (orphan-parent invariant in Field::Base), so the
+    # ordering is exhaustive across the three valid shapes.
+    #
+    # `for_entity(name, scope:, parent_scope:)` returns the union across
+    # all three shapes on a collision, and a bare `index_by(&:name)` would
+    # let DB row order pick the winner. Shared by the class-query path
     # (ClassQueryMethods#where_typed_eav) and the instance path
     # (InstanceMethods#typed_eav_defs_by_name) so the two can't drift.
     def self.definitions_by_name(defs)
-      defs.to_a.sort_by { |d| d.scope.nil? ? 0 : 1 }.index_by(&:name)
+      defs.to_a
+          .sort_by { |d| [d.scope.nil? ? 0 : 1, d.parent_scope.nil? ? 0 : 1] }
+          .index_by(&:name)
     end
 
     # Indexes field definitions by name into a multi-map (one name →
@@ -55,13 +73,49 @@ module TypedEAV
       # Register this model as having typed fields.
       #
       # Options:
-      #   scope_method: - method name that returns a scope value (e.g. :tenant_id)
-      #                   for multi-tenant field isolation
-      #   types:        - restrict which field types are allowed (array of symbols)
-      #                   e.g. [:text, :integer, :boolean]
-      #                   default: all types
+      #   scope_method:        - method name that returns a scope value (e.g. :tenant_id)
+      #                          for multi-tenant field isolation. Optional; nil means
+      #                          the model is "global" (no per-tenant partitioning).
+      #   parent_scope_method: - method name that returns a parent_scope value
+      #                          (e.g. :workspace_id) for two-level partitioning under
+      #                          `scope_method:`. Optional; nil means the model uses a
+      #                          single-axis partition. REQUIRES `scope_method:` to also
+      #                          be set — declaring `parent_scope_method:` alone raises
+      #                          `ArgumentError` at class load (see below).
+      #   types:               - restrict which field types are allowed (array of symbols)
+      #                          e.g. [:text, :integer, :boolean]
+      #                          default: all types
+      #   versioned:           - Phase 04 opt-in: when true, mutations to typed values on
+      #                          this entity type are recorded in typed_eav_value_versions.
+      #                          Requires `TypedEAV.config.versioning = true` (the gem-
+      #                          level master switch — default false). Apps that want
+      #                          versioning per-entity rather than globally toggle this
+      #                          alongside the master switch in their initializer.
+      #                          Alternative API: `include TypedEAV::Versioned` AFTER
+      #                          `has_typed_eav` does the same thing (see
+      #                          lib/typed_eav/versioned.rb).
+      #
+      # Configuration error: `parent_scope_method:` without `scope_method:` raises
+      # `ArgumentError` at class load time. This closes the silent dead-letter mode
+      # where ambient scope resolution would short-circuit to `[nil, nil]` for a model
+      # declaring parent_scope but no scope, routing every query to the global-only
+      # branch and silently discarding the parent_scope intent.
+      #
       # Public DSL macro modeled on `acts_as_*`; renaming would break callers.
-      def has_typed_eav(scope_method: nil, types: nil) # rubocop:disable Naming/PredicatePrefix
+      def has_typed_eav(scope_method: nil, parent_scope_method: nil, types: nil, versioned: false) # rubocop:disable Naming/PredicatePrefix
+        # Macro-time configuration guard. Failing fast at class-load time is strictly
+        # better than at query time because the misconfiguration is static (a
+        # property of the macro call, not of the request). Closes the silent
+        # dead-letter mode that would otherwise route every parent-scope-aware
+        # query to the global-only branch.
+        if parent_scope_method && !scope_method
+          raise ArgumentError,
+                "has_typed_eav: `parent_scope_method:` requires `scope_method:` to also be set. " \
+                "A model declaring parent_scope without scope is a configuration error — " \
+                "ambient resolution would silently return [nil, nil] and queries would dead-letter. " \
+                "Either add `scope_method: :your_scope_method` or remove `parent_scope_method:`."
+        end
+
         # class_attribute rather than cattr_accessor: class variables are
         # copied-on-write across subclasses and reload well under Rails'
         # code reloader. Normalize the types list to strings once so hot
@@ -69,6 +123,8 @@ module TypedEAV
         # don't have to re-map per call.
         class_attribute :typed_eav_scope_method, instance_accessor: false,
                                                  default: scope_method
+        class_attribute :typed_eav_parent_scope_method, instance_accessor: false,
+                                                        default: parent_scope_method
         class_attribute :allowed_typed_eav_types, instance_accessor: false,
                                                   default: types && types.map(&:to_s).freeze
 
@@ -85,7 +141,7 @@ module TypedEAV
         accepts_nested_attributes_for :typed_values, allow_destroy: true
 
         # Register with the global registry
-        TypedEAV.registry.register(name, types: types)
+        TypedEAV.registry.register(name, types: types, versioned: versioned)
       end
     end
 
@@ -116,8 +172,18 @@ module TypedEAV
       #     { 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)
+      #
+      # Single-scope BC: callers that don't pass `parent_scope:` see no
+      # behavior change. The kwarg defaults to `UNSET_SCOPE` — ambient
+      # resolution applies if the model declares `parent_scope_method:`,
+      # otherwise resolves to nil.
+      #
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- input normalization + multimap branch + filter dispatch genuinely belong together; splitting hurts readability of the scope-collision logic.
-      def where_typed_eav(*filters, scope: UNSET_SCOPE)
+      def where_typed_eav(*filters, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE)
         # Normalize input: accept splat args, a single array, a single filter hash,
         # a hash-of-hashes (form params), or ActionController::Parameters.
         filters = filters.map { |f| f.respond_to?(:to_unsafe_h) ? f.to_unsafe_h : f }
@@ -142,19 +208,24 @@ module TypedEAV
 
         filters = Array(filters)
 
-        # Resolve the scope once so we can branch on whether we're inside
-        # `TypedEAV.unscoped { }` (ALL_SCOPES) or a normal single-scope
-        # query. Under ALL_SCOPES the same name can legitimately appear
-        # across multiple tenant partitions; collapsing to one definition
-        # would silently drop all but one tenant's matches. See the
-        # multimap branch below.
-        resolved = resolve_scope(scope)
+        # Resolve the (scope, parent_scope) tuple once so we can branch on
+        # whether we're inside `TypedEAV.unscoped { }` (ALL_SCOPES) or a
+        # normal single-scope query. Under ALL_SCOPES the same name can
+        # legitimately appear across multiple tenant partitions; collapsing
+        # to one definition would silently drop all but one tenant's
+        # matches. See the multimap branch below.
+        resolved = resolve_scope(scope, parent_scope)
         all_scopes = resolved.equal?(ALL_SCOPES)
 
         defs = if all_scopes
-                 TypedEAV::Field::Base.where(entity_type: name)
+                 # Multimap branch is structurally unchanged — atomic-bypass
+                 # per CONTEXT.md drops both scope AND parent_scope predicates.
+                 # The OR-collapse at field_id level naturally OR's across all
+                 # (scope, parent_scope) combinations.
+                 TypedEAV::Partition.visible_fields(entity_type: name, mode: :all_partitions)
                else
-                 TypedEAV::Field::Base.for_entity(name, scope: resolved)
+                 s, ps = resolved
+                 TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
                end
 
         if all_scopes
@@ -212,44 +283,321 @@ module TypedEAV
       #   Contact.with_field("active", true)      # op defaults to :eq
       #   Contact.with_field("name", :contains, "smith")
       #
-      def with_field(name, operator_or_value = nil, value = nil, scope: UNSET_SCOPE)
+      # 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)
         if value.nil? && !operator_or_value.is_a?(Symbol)
           # Two-arg form: with_field("name", "value") implies :eq
-          where_typed_eav({ name: name, op: :eq, value: operator_or_value }, scope: scope)
+          where_typed_eav(
+            { name: name, op: :eq, value: operator_or_value },
+            scope: scope, parent_scope: parent_scope,
+          )
         else
-          where_typed_eav({ name: name, op: operator_or_value, value: value }, scope: scope)
+          where_typed_eav(
+            { name: name, op: operator_or_value, value: value },
+            scope: scope, parent_scope: parent_scope,
+          )
         end
       end
 
       # Returns field definitions for this entity type.
       #
-      # `scope:` behavior:
+      # `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 fields (prior behavior preserved)
-      def typed_eav_definitions(scope: UNSET_SCOPE)
-        resolved = resolve_scope(scope)
+      #   - 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::Field::Base.where(entity_type: name)
+          TypedEAV::Partition.visible_fields(entity_type: name, mode: :all_partitions)
         else
-          TypedEAV::Field::Base.for_entity(name, scope: resolved)
+          s, ps = resolved
+          TypedEAV::Partition.visible_fields(entity_type: name, scope: s, parent_scope: ps)
         end
       end
 
-      private
+      # Bulk read API. Returns `{ record_id => { field_name => value } }` for
+      # an Enumerable of host records — the class-method bulk variant of
+      # `InstanceMethods#typed_eav_hash`. N+1-free regardless of record count
+      # or field count.
+      #
+      # Why this method exists: list pages and reports often need typed values
+      # for many records at once. Calling `record.typed_eav_hash` per record
+      # issues 2 queries per record (value preload + field preload) — that's
+      # 200 queries for 100 records. This method collapses to:
+      #
+      #   - 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
+      #     (for `typed_eav_definitions` / `winning_ids_by_name` per tuple)
+      #
+      # Total: 2 + (unique partition tuples) queries — typically 3 or 4 in
+      # practice, INDEPENDENT of record count.
+      #
+      # We group records by `[typed_eav_scope, typed_eav_parent_scope]` BEFORE
+      # the value preload because field-collision resolution
+      # (`HasTypedEAV.definitions_by_name`) varies by partition: name "age"
+      # in tenant_1 may have a different field_id than "age" in tenant_2,
+      # and the global+scoped collision precedence must be applied per-tuple.
+      # The value preload itself is a single query regardless — `WHERE
+      # entity_type=? AND entity_id IN (?)` is a single index seek.
+      #
+      # Orphan-skip + winning-id precedence mirrored from the per-record
+      # instance method (`#typed_eav_hash`, lines 584–606). Class-query path
+      # and instance path share the same `HasTypedEAV.definitions_by_name`
+      # collision-precedence helper so the two cannot drift.
+      #
+      # Phase 7 cache integration deferred per 06-CONTEXT.md §Open Questions.
+      # This method ships preload-only; it does not call any cache primitive
+      # and does not collide with the future Phase 7 `with_all_typed_values`
+      # scope or `typed_eav_hash_cached` alias.
+      #
+      # The Metrics/* disables at the top of `where_typed_eav` (line 185)
+      # cover this method too — the partition-tuple grouping + single
+      # preload + collision-precedence loop genuinely belong together, same
+      # rationale as the where_typed_eav disable.
+      def typed_eav_hash_for(records)
+        # Input validation — fail fast with a recovery hint (CONVENTIONS §Error
+        # messages). nil is a programmer error (a real empty list is `[]`).
+        raise ArgumentError, "typed_eav_hash_for requires an Enumerable of records, got nil" if records.nil?
+
+        # Coerce to Array. Accepts AR::Relation, Array, lazy enumerable. We
+        # need to iterate twice (group_by + map(&:id) + final iteration) so
+        # materialize once.
+        records = records.to_a
+        return {} if records.empty?
+
+        # Single-class invariant: the polymorphic value query (`entity_type:
+        # name`) targets ONE class; mixed-class input would silently miss
+        # rows of the other class. The defensive check is cheap (one `all?`
+        # pass) and surfaces the misuse loudly. STI subclasses pass via
+        # `Class#===` which dispatches to `is_a?` (covariant). `all?(self)`
+        # is the rubocop-preferred form for a kind-of check.
+        unless records.all?(self)
+          classes = records.map { |r| r.class.name }.uniq
+          raise ArgumentError,
+                "typed_eav_hash_for expects records of class #{name} (or its subclasses); " \
+                "got mixed classes: #{classes.join(", ")}"
+        end
+
+        # Group by partition tuple BEFORE field-definition lookup. Ruby Hash
+        # handles nil keys cleanly, so `[nil, nil]` (the global partition) is
+        # a valid tuple — no special casing.
+        groups = records.group_by { |r| [r.typed_eav_scope, r.typed_eav_parent_scope] }
+
+        # Build per-tuple `winning_ids_by_name`. One `typed_eav_definitions`
+        # query per unique tuple; reuse the resulting map for every record in
+        # that tuple. `HasTypedEAV.definitions_by_name` is the SHARED
+        # collision-precedence function — same one `typed_eav_defs_by_name`
+        # uses on the instance side. Reusing it guarantees parity.
+        winning_ids_by_tuple = groups.keys.each_with_object({}) do |(s, ps), memo|
+          defs = typed_eav_definitions(scope: s, parent_scope: ps)
+          memo[[s, ps]] = HasTypedEAV.definitions_by_name(defs).transform_values(&:id)
+        end
 
-      # Resolves the scope kwarg into a concrete value for field-definition
-      # lookup. See `typed_eav_definitions` docs for kwarg semantics.
-      # Raises `TypedEAV::ScopeRequired` when the model declares
-      # `scope_method:` but ambient scope can't be resolved and fail-closed
-      # mode is enabled.
-      def resolve_scope(explicit)
-        # Explicit override (including explicit nil) — use verbatim.
-        return TypedEAV.normalize_scope(explicit) unless explicit.equal?(UNSET_SCOPE)
+        # Single-shot value preload across ALL records, regardless of how
+        # many partition tuples they span. `includes(:field)` triggers a
+        # second query that batch-loads every referenced field row — Rails'
+        # standard preload pattern. Splitting this per-tuple would issue N
+        # value queries instead of 1; the SQL `WHERE entity_id IN (...)`
+        # is a single index seek.
+        #
+        # We use the explicit `entity_type: name` form rather than
+        # `where(entity: records)` because empty `records` would have made
+        # the `where(entity:)` form ambiguous earlier — but we already
+        # short-circuited on empty, so either works. Explicit form reads
+        # cleaner.
+        value_rows = TypedEAV::Value
+                     .includes(:field)
+                     .where(entity_type: name, entity_id: records.map(&:id))
+                     .to_a
+        values_by_record_id = value_rows.group_by(&:entity_id)
+
+        # Build the result hash. Records with no values produce a `{}` inner
+        # hash — present in the result so callers can uniformly index by id.
+        records.each_with_object({}) do |record, result|
+          inner = {}
+          tuple_key = [record.typed_eav_scope, record.typed_eav_parent_scope]
+          winning_ids_by_name = winning_ids_by_tuple.fetch(tuple_key, {})
+
+          values_by_record_id.fetch(record.id, []).each do |tv|
+            # Skip orphans (`tv.field` nil — definition deleted via raw SQL
+            # or a Phase 02 `:nullify` cascade). Same fail-soft contract as
+            # `#typed_eav_hash` line 591.
+            next unless tv.field
+
+            field_name = tv.field.name
+            winning_id = winning_ids_by_name[field_name]
+            effective_id = tv.field_id || tv.field&.id
+
+            # When a winner IS registered: only its row is allowed (collision
+            # precedence — scoped beats global). When no winner is registered
+            # (definition deleted while values remain), fall back to first-
+            # wins so the hash isn't lossy. Mirrors `#typed_eav_hash` lines
+            # 600–605.
+            if winning_id
+              inner[field_name] = tv.value if effective_id == winning_id
+            else
+              inner[field_name] = tv.value unless inner.key?(field_name)
+            end
+          end
 
-        # Inside `TypedEAV.unscoped { }` — skip the scope filter entirely.
+          result[record.id] = inner
+        end
+      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. Bad records roll
+      # back their savepoint and surface in `errors_by_record`; good records
+      # commit when the outer transaction commits.
+      #
+      # ## Failure isolation contract (CONTEXT-locked, 06-CONTEXT.md line 26)
+      #
+      #   outer transaction
+      #   ├── savepoint(record_1) → record.typed_eav_attributes = vbn; record.save
+      #   ├── savepoint(record_2) → ditto
+      #   └── savepoint(record_N) → ditto
+      #
+      # The savepoint-per-record-INSIDE-an-outer-transaction structure is
+      # preserved under EVERY `version_grouping:` value (none / per_record /
+      # per_field). It is NEVER relaxed to per-record TOP-LEVEL transactions
+      # — that path was rejected at CONTEXT time because per-record top-level
+      # transactions break Phase 3 hook semantics (after_commit fires on
+      # outer commit, not savepoint release; see Plan 06-05 §Discrepancy
+      # awareness).
+      #
+      # ## Why we delegate to record.typed_eav_attributes=
+      #
+      # The instance setter at lines 632–664 ALREADY enforces:
+      #   * Field-name resolution via `typed_eav_defs_by_name` (collision-
+      #     precedence-correct).
+      #   * `allowed_typed_eav_types` restriction (silently skips fields whose
+      #     type was excluded by `has_typed_eav types: [...]`).
+      #   * Cross-tenant guards via `validate_field_scope_matches_entity` on
+      #     the resulting Value rows.
+      # Bulk write reuses this path; it does NOT bypass any of these.
+      #
+      # ## Errors-by-record key choice
+      #
+      # The Hash KEY is the record itself (NOT record.id). Records that fail
+      # validation BEFORE getting an id (new records that never persist) have
+      # nil ids; using id as the key would collapse multiple unsaved-record
+      # failures into one entry and lose information. Callers can still
+      # `result[:errors_by_record].keys.map(&:id)` if they want id-keyed
+      # output.
+      #
+      # ## errors_by_record value shape
+      #
+      # `record.errors.messages.transform_keys(&:to_s)` — string field-name
+      # keys, Array<String> messages. Mirrors `CSVMapper::Result#errors` so
+      # callers can write one error-handling path that consumes both shapes.
+      # `errors.messages` is the modern AR API (the older `errors.to_h` is
+      # flagged by Rails/DeprecatedActiveModelErrorsMethods); both return the
+      # same shape `{attribute => [messages]}`.
+      #
+      # ## version_grouping default sentinel
+      #
+      # The kwarg's literal default is `:default`. The first step of the
+      # method body resolves it: `:per_record` when versioning is on, `:none`
+      # when versioning is off. Callers omitting the kwarg "just work" in
+      # both versioning environments — they don't need to branch on
+      # `TypedEAV.config.versioning`. Explicit `:per_record`/`:per_field`
+      # passed with versioning OFF raises ArgumentError loudly (the caller's
+      # intent — group versions — cannot be satisfied with versioning off,
+      # and silently no-op'ing would mask a misconfiguration). Explicit
+      # `:none` is ALWAYS valid (explicit opt-out — same payload as the
+      # default-resolved case under versioning-off).
+      #
+      # ## Snapshot mechanism for version_group_id propagation
+      #
+      # The `:per_record` and `:per_field` paths stamp `pending_version_group_id`
+      # on each affected Value object BEFORE save inside the per-record
+      # `with_context` block. The Phase 4 versioning subscriber prefers the
+      # per-Value snapshot over `context[:version_group_id]` so the UUID
+      # survives the outer-transaction `after_commit` boundary even after
+      # `with_context` has unwound. See `lib/typed_eav/versioning/subscriber.rb`
+      # line 127 for the read-side; the stamping happens below per-record.
+      # `with_context(version_group_id: ...)` is retained as a belt-and-
+      # suspenders fallback so any future after_commit-inside-savepoint
+      # dispatch path also works.
+      #
+      # ## rubocop scope
+      #
+      # The Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength,
+      # Metrics/PerceivedComplexity disables on `where_typed_eav` (line 185
+      # of this file) are still active at this point — they cover the entire
+      # ClassQueryMethods module body and re-enable only at line 629 (after
+      # `typed_eav_attributes=`). The bulk-write transaction + savepoint +
+      # error-capture + version-group-id snapshot legitimately belong
+      # together for the same reason `where_typed_eav` does — splitting
+      # hurts readability of the failure-isolation invariant.
+      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
+
+      # Resolves the scope and parent_scope kwargs into a concrete tuple for
+      # field-definition lookup. See `typed_eav_definitions` docs for kwarg
+      # semantics.
+      #
+      # 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.
+      #
+      # Resolver-callable contract violations (`Config.scope_resolver`
+      # returning a bare scalar) raise `ArgumentError` directly inside
+      # `TypedEAV.current_scope` (plan 02), BEFORE this method consumes the
+      # value. By the time `resolve_scope` calls `TypedEAV.current_scope`,
+      # the result is guaranteed to be `nil` or a 2-element Array — no shape
+      # check is duplicated here; that would be dead code.
+      def resolve_scope(explicit_scope, explicit_parent_scope)
+        # Inside `TypedEAV.unscoped { }` — atomic bypass, drops both predicates
+        # entirely (per CONTEXT.md). The multimap branch in `where_typed_eav`
+        # handles ALL_SCOPES; do not narrow to per-axis predicates inside unscoped.
         return ALL_SCOPES if TypedEAV.unscoped?
 
+        # Determine the explicit-overrides path. If EITHER kwarg was passed
+        # explicitly (i.e., not UNSET_SCOPE), normalize what was given and skip
+        # ambient resolution entirely. Mixing explicit + ambient resolution
+        # within one call would be confusing; explicit wins for the whole tuple.
+        explicit_given = !explicit_scope.equal?(UNSET_SCOPE) || !explicit_parent_scope.equal?(UNSET_SCOPE)
+
+        if explicit_given
+          # Per-slot normalize: an explicit kwarg passes through `normalize_scope`
+          # to coerce scalars/AR-records to strings, with UNSET_SCOPE collapsing
+          # to nil for the corresponding slot. We pass `[value, nil]` to extract
+          # the first slot and `[nil, value]` to extract the second so the
+          # public `normalize_scope` BC contract (used by with_scope) handles
+          # the per-slot coercion uniformly.
+          s = if explicit_scope.equal?(UNSET_SCOPE)
+                nil
+              else
+                TypedEAV.normalize_scope([explicit_scope, nil]).first
+              end
+          ps = if explicit_parent_scope.equal?(UNSET_SCOPE)
+                 nil
+               else
+                 TypedEAV.normalize_scope([nil, explicit_parent_scope]).last
+               end
+          # Orphan-parent invariant at the read layer: a request for parent_scope
+          # without scope is dead-letter (no rows can match — the Field-level
+          # validator forbids `(scope=NULL, parent_scope=NOT NULL)` rows). Don't
+          # raise here — just narrow the predicate. The Field-level invariant
+          # (plan 03) prevents the corresponding write.
+          return [s, ps]
+        end
+
         # Models that did NOT opt into scoping must NOT see ambient scope.
         # If the host declared `has_typed_eav` without `scope_method:`, it
         # has no per-instance scope accessor, so `Value#validate_field_scope_matches_entity`
@@ -259,23 +607,34 @@ module TypedEAV
         # leak cross-model ambient state into a model that never opted in.
         # An explicit `scope:` kwarg (handled above) still overrides this, so
         # admin/test paths retain the ability to query arbitrary scopes.
-        return nil unless typed_eav_scope_method
-
-        # Ambient resolver (via `with_scope` stack or configured lambda).
+        #
+        # NOTE: a model with `parent_scope_method:` but no `scope_method:` is
+        # impossible to construct — the macro-time guard in `has_typed_eav`
+        # raises `ArgumentError` at class-load time. If we get here, either
+        # both are set or only `scope_method` is set, never only
+        # `parent_scope_method`.
+        return [nil, nil] unless typed_eav_scope_method
+
+        # Ambient resolver (via `with_scope` stack or configured lambda). The
+        # return value is already validated as `nil | [a, b]` by
+        # `TypedEAV.current_scope` — no shape check needed here.
         resolved = TypedEAV.current_scope
-        return resolved unless resolved.nil?
-
-        # Fail-closed: the model opted into scoping (`scope_method:` declared)
-        # but nothing resolved. Raise so data can't leak across partitions.
-        if typed_eav_scope_method && TypedEAV.config.require_scope
-          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."
+        if resolved.nil?
+          # Fail-closed: the model opted into scoping (`scope_method:` declared)
+          # but nothing resolved. Raise so data can't leak across partitions.
+          if TypedEAV.config.require_scope
+            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
+          return [nil, nil]
         end
 
-        nil
+        # `resolved` is guaranteed to be a 2-element Array by current_scope's
+        # contract (plan 02). Return verbatim — both halves already normalized.
+        resolved
       end
     end
 
@@ -285,7 +644,10 @@ module TypedEAV
     module InstanceMethods
       # The field definitions available for this record
       def typed_eav_definitions
-        self.class.typed_eav_definitions(scope: typed_eav_scope)
+        self.class.typed_eav_definitions(
+          scope: typed_eav_scope,
+          parent_scope: typed_eav_parent_scope,
+        )
       end
 
       # Current scope value (for multi-tenant)
@@ -295,6 +657,19 @@ module TypedEAV
         send(self.class.typed_eav_scope_method)&.to_s
       end
 
+      # Current parent_scope value (for two-level partitioning).
+      #
+      # Returns nil for models that did not declare `parent_scope_method:` —
+      # the method is defined unconditionally so callers (e.g. the Value-side
+      # cross-axis validator) can `respond_to?` and read uniformly without
+      # branching on `parent_scope_method` configuration. Mirrors the
+      # `&.to_s` normalization on `typed_eav_scope`.
+      def typed_eav_parent_scope
+        return nil unless self.class.typed_eav_parent_scope_method
+
+        send(self.class.typed_eav_parent_scope_method)&.to_s
+      end
+
       # Build missing values with defaults for all available fields.
       # Useful in forms to show all fields even when no value exists yet.
       #
@@ -476,8 +851,30 @@ module TypedEAV
       # when both a global (scope=NULL) and a scoped field share a name, the
       # scoped definition wins. Delegates to `HasTypedEAV.definitions_by_name`
       # so the class-query path and the instance path share one source of truth.
+      #
+      # ## Bulk-write memoization (Phase 06 plan 05)
+      #
+      # `bulk_set_typed_eav_values` sets `Thread.current[:typed_eav_bulk_defs_memo]`
+      # to a Hash before its records loop. We consult it here so the per-
+      # record `typed_eav_attributes=` call does NOT issue a fresh
+      # `typed_eav_definitions` SELECT per record. AR's per-block query
+      # cache (`ActiveRecord::Base.cache`) is invalidated by every write —
+      # because each record's INSERT clears the cache — so cache-do alone
+      # cannot keep field-definition reads N+1-free across the bulk loop.
+      # The thread-local memo is the explicit fallback documented in plan
+      # 06-05 §T3 notes; it pre-warms once per `[host_class, scope,
+      # parent_scope]` tuple and reuses across every record in that tuple.
+      #
+      # Outside a bulk operation the memo is nil and we fall through to
+      # the standard read path — zero overhead.
       def typed_eav_defs_by_name
-        HasTypedEAV.definitions_by_name(typed_eav_definitions)
+        memo = Thread.current[:typed_eav_bulk_defs_memo]
+        if memo
+          key = [self.class.name, typed_eav_scope, typed_eav_parent_scope]
+          memo[key] ||= HasTypedEAV.definitions_by_name(typed_eav_definitions)
+        else
+          HasTypedEAV.definitions_by_name(typed_eav_definitions)
+        end
       end
     end
   end