typed_eav 0.1.0 → 0.2.1

data/lib/generators/typed_eav/scaffold/templates/controllers/typed_eav_controller.rb

@@ -31,7 +31,7 @@ class TypedEAVController < ApplicationController
   before_action :set_field, only: %i[show edit update destroy]
 
   def index
-    @fields = scoped_fields.order(:entity_type, :scope, :sort_order, :name)
+    @fields = scoped_fields.order(:entity_type, :scope, :parent_scope, :sort_order, :name)
   end
 
   def show; end
@@ -45,19 +45,20 @@ class TypedEAVController < ApplicationController
 
   def create
     type_class = resolve_type_class(params.dig(:typed_eav_field, :field_type) || params[:type])
-    ambient = ensure_scope!
+    partition = ensure_partition!
     attrs = field_params(type_class, creating: true)
-    attrs[:scope] = ambient
+    attrs[:scope] = partition[:scope]
+    attrs[:parent_scope] = partition[:parent_scope]
     attrs[:section_id] = verified_section_id(
       params.dig(:typed_eav_field, :section_id),
       attrs[:entity_type],
-      ambient
+      partition,
     )
     @field = type_class.new(attrs)
 
     if @field.save
       redirect_to edit_typed_eav_field_path(@field), status: :see_other,
-        notice: "Field created."
+                                                     notice: "Field created."
     else
       render :new, status: :unprocessable_content
     end
@@ -68,12 +69,12 @@ class TypedEAVController < ApplicationController
     attrs[:section_id] = verified_section_id(
       params.dig(:typed_eav_field, :section_id),
       @field.entity_type,
-      @field.scope
+      field_partition(@field),
     )
 
     if @field.update(attrs)
       redirect_to edit_typed_eav_field_path(@field), status: :see_other,
-        notice: "Field updated."
+                                                     notice: "Field updated."
     else
       render :edit, status: :unprocessable_content
     end
@@ -94,7 +95,7 @@ class TypedEAVController < ApplicationController
       @field.field_options.create!(
         label: params[:option_label],
         value: params[:option_value],
-        sort_order: next_order
+        sort_order: next_order,
       )
     end
     redirect_to edit_typed_eav_field_path(@field), status: :see_other
@@ -120,73 +121,77 @@ class TypedEAVController < ApplicationController
     @field = scoped_fields.find(params[:id])
   end
 
-  # Base relation filtered to the current ambient scope. Fields with
-  # scope=NULL (global fields visible to all partitions) are always
-  # included. Fail-closed semantics:
-  #   - unscoped?               -> ALL fields across every scope (admin override)
-  #   - scope present           -> fields for that scope UNION globals
-  #   - scope nil, require_scope=true  -> raise TypedEAV::ScopeRequired
-  #   - scope nil, require_scope=false -> globals only (scope=NULL); never
-  #                                       leaks other tenants' rows.
+  # Base relation filtered through TypedEAV's partition seam. Fields with the
+  # global tuple `(scope=NULL, parent_scope=NULL)` are visible to every
+  # partition. Fail-closed semantics:
+  #   - unscoped?                    -> ALL fields across every partition
+  #   - [scope, parent_scope] present -> global + scope + full-tuple fields
+  #   - no tuple, require_scope=true  -> raise TypedEAV::ScopeRequired
+  #   - no tuple, require_scope=false -> global fields only; never leaks
+  #                                     other tenants' rows.
   # Use `TypedEAV.with_scope(value) { }` or configure
-  # `TypedEAV.config.scope_resolver` to set the scope.
+  # `TypedEAV.config.scope_resolver` to set the tuple.
   def scoped_fields
-    # Inside `TypedEAV.unscoped { }` the caller has explicitly opted into
-    # cross-scope visibility (admin/migration paths). Skip the scope filter
-    # entirely so the scaffold remains usable instead of raising under
-    # require_scope=true.
-    return TypedEAV::Field::Base.all if TypedEAV.unscoped?
+    partition = current_partition!
+    return TypedEAV::Field::Base.all if partition[:mode] == :all_partitions
 
-    scope = TypedEAV.current_scope
-    return TypedEAV::Field::Base.where(scope: [scope, nil]) if scope
+    TypedEAV::Field::Base.where(id: visible_field_ids(partition))
+  end
 
-    if TypedEAV.config.require_scope
-      raise TypedEAV::ScopeRequired,
-        "TypedEAV.current_scope is nil and require_scope is enabled; " \
-        "wrap the request in TypedEAV.with_scope(value) { } or configure " \
-        "TypedEAV.config.scope_resolver."
-    end
+  # Resolve the ambient tuple for writes. Mirrors `scoped_fields` semantics:
+  #   - unscoped?                    -> returns the global tuple
+  #   - [scope, parent_scope] present -> returns that tuple
+  #   - no tuple, require_scope=true  -> raises TypedEAV::ScopeRequired
+  #   - no tuple, require_scope=false -> returns the global tuple
+  def ensure_partition!
+    current_partition!.slice(:scope, :parent_scope)
+  end
 
-    TypedEAV::Field::Base.where(scope: nil)
+  # Server-side verification that the requested section exists within the same
+  # partition tuple as the field being created or updated, including global
+  # sections visible to that tuple.
+  # Returns nil if `id` is blank. Raises ActiveRecord::RecordNotFound (Rails
+  # renders 404) if the id does not belong to a section the caller can see,
+  # blocking cross-tenant assignment via a forged section_id.
+  def verified_section_id(id, entity_type, partition)
+    return nil if id.blank?
+
+    TypedEAV::Partition.find_visible_section!(
+      id,
+      entity_type: entity_type,
+      **partition,
+    ).id
   end
 
-  # Resolve the ambient scope for writes. Mirrors `scoped_fields` semantics:
-  #   - unscoped?               -> returns nil (admin override; new field is global)
-  #   - scope present           -> returns the scope value
-  #   - scope nil, require_scope=true  -> raises TypedEAV::ScopeRequired
-  #   - scope nil, require_scope=false -> returns nil (global-field creation)
-  def ensure_scope!
-    # Inside `TypedEAV.unscoped { }` we deliberately bypass the require_scope
-    # guard so admin tools can create global fields without first declaring an
-    # ambient scope. Wrap in `with_scope` to write into a specific tenant.
-    return nil if TypedEAV.unscoped?
+  def current_partition!
+    return { scope: nil, parent_scope: nil, mode: :all_partitions } if TypedEAV.unscoped?
 
-    scope = TypedEAV.current_scope
-    return scope if scope
+    tuple = TypedEAV.current_scope
+    return { scope: tuple.first, parent_scope: tuple.last, mode: :partition } if tuple
 
     if TypedEAV.config.require_scope
       raise TypedEAV::ScopeRequired,
-        "TypedEAV.current_scope is nil and require_scope is enabled; " \
-        "wrap the request in TypedEAV.with_scope(value) { } or configure " \
-        "TypedEAV.config.scope_resolver."
+            "TypedEAV.current_scope is nil and require_scope is enabled; " \
+            "wrap the request in TypedEAV.with_scope(value) { } or configure " \
+            "TypedEAV.config.scope_resolver."
     end
 
-    nil
+    { scope: nil, parent_scope: nil, mode: :partition }
   end
 
-  # Server-side verification that the requested section exists within the
-  # caller's entity_type + scope (or globals). `Section.for_entity` unions
-  # scope=NULL globals with the scoped rows, matching field visibility.
-  # Returns nil if `id` is blank. Raises ActiveRecord::RecordNotFound (Rails
-  # renders 404) if the id does not belong to a section the caller can see,
-  # blocking cross-tenant assignment via a forged section_id.
-  def verified_section_id(id, entity_type, scope)
-    return nil if id.blank?
-    TypedEAV::Section.for_entity(entity_type, scope: scope).find(id).id
+  def field_partition(field)
+    { scope: field.scope, parent_scope: field.parent_scope, mode: :partition }
+  end
+
+  def visible_field_ids(partition)
+    TypedEAV::Field::Base.distinct.pluck(:entity_type).flat_map do |entity_type|
+      TypedEAV::Partition.visible_fields(entity_type: entity_type, **partition).pluck(:id)
+    end
   end
 
   def resolve_type_class(type_name)
     return TypedEAV::Field::Text if type_name.blank?
+
     TypedEAV.config.field_class_for(type_name)
   rescue ArgumentError
     TypedEAV::Field::Text
@@ -195,11 +200,12 @@ class TypedEAVController < ApplicationController
   # Data-driven permitted params based on what the field type exposes via
   # store_accessor. Much cleaner than a massive case statement per type.
   #
-  # NOTE: `scope` and `section_id` are intentionally NOT in the permit list.
-  # `scope` is derived server-side from the ambient scope in `create`; a
+  # NOTE: `scope`, `parent_scope`, and `section_id` are intentionally NOT in
+  # the permit list. `scope` and `parent_scope` are derived server-side from
+  # the ambient partition tuple in `create`; a
   # client-supplied value would let any authenticated user write into another
-  # tenant's partition. `section_id` is verified against a scoped Section
-  # lookup via `verified_section_id` on both create and update.
+  # tenant's partition. `section_id` is verified against the partition seam via
+  # `verified_section_id` on both create and update.
   def field_params(type_class, creating:)
     base = %i[name required sort_order]
     base += %i[entity_type] if creating
@@ -208,11 +214,11 @@ class TypedEAVController < ApplicationController
     option_keys = option_keys_for(type_class)
 
     # Default value is scalar for most types, array for array types
-    if type_class.method_defined?(:array_field?) && type_class.allocate.array_field?
-      permitted = base + option_keys + [default_value: []]
-    else
-      permitted = base + option_keys + %i[default_value]
-    end
+    permitted = if type_class.method_defined?(:array_field?) && type_class.allocate.array_field?
+                  base + option_keys + [{ default_value: [] }]
+                else
+                  base + option_keys + %i[default_value]
+                end
 
     params.require(:typed_eav_field).permit(*permitted).tap do |attrs|
       attrs.transform_values! do |value|
@@ -224,6 +230,7 @@ class TypedEAVController < ApplicationController
   # Introspect which option keys the field type exposes
   def option_keys_for(type_class)
     return [] unless type_class.respond_to?(:stored_attributes)
+
     (type_class.stored_attributes[:options] || []).map(&:to_sym)
   rescue StandardError
     []

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_common_fields.html.erb

@@ -38,11 +38,21 @@
 
 <div>
   <label>Scope</label>
-  <%# The controller derives scope from the ambient value (TypedEAV.current_scope)
-      and never permits it from params. Display it read-only so users can see which
+  <%# The controller derives scope from the ambient partition tuple and never
+      permits it from params. Display it read-only so users can see which
       partition this field belongs to without implying they can change it. %>
+  <% current_partition = field.new_record? ? TypedEAV.current_scope : nil %>
+  <% current_partition_scope = current_partition&.first %>
+  <% current_partition_parent_scope = current_partition&.last %>
   <input type="text"
-         value="<%= field.scope.presence || (field.new_record? ? (TypedEAV.current_scope || "Global (all scopes)") : "Global (all scopes)") %>"
+         value="<%= field.scope.presence || (current_partition_scope.presence || "Global (all scopes)") %>"
+         disabled readonly />
+</div>
+
+<div>
+  <label>Parent Scope</label>
+  <input type="text"
+         value="<%= field.parent_scope.presence || (current_partition_parent_scope.presence || "Global (all parent scopes)") %>"
          disabled readonly />
 </div>
 

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/index.html.erb

@@ -17,6 +17,7 @@
       <th>Name</th>
       <th>Required</th>
       <th>Scope</th>
+      <th>Parent Scope</th>
       <th>Options</th>
       <th>Default</th>
       <th></th>
@@ -32,6 +33,7 @@
         <td><%= field.name %></td>
         <td><%= field.required? ? "Yes" : "" %></td>
         <td><code><%= field.scope.inspect %></code></td>
+        <td><code><%= field.parent_scope.inspect %></code></td>
         <td><code><%= field.options %></code></td>
         <td><code><%= field.default_value.inspect %></code></td>
         <td><%= button_to "Delete", typed_eav_field_path(field), method: :delete,

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/show.html.erb

@@ -19,6 +19,9 @@
   <dt>Scope</dt>
   <dd><code><%= @field.scope.inspect %></code></dd>
 
+  <dt>Parent Scope</dt>
+  <dd><code><%= @field.parent_scope.inspect %></code></dd>
+
   <dt>Options</dt>
   <dd><code><%= @field.options %></code></dd>
 

data/lib/typed_eav/bulk_write.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  # Internal executor for host-class bulk typed-value writes.
+  #
+  # Host models keep the public `bulk_set_typed_eav_values` API; this module
+  # owns the transaction shape, savepoint isolation, error aggregation, field
+  # name resolution delegation, and version-group stamping.
+  module BulkWrite
+    class << self
+      def execute(host_class:, records:, values_by_field_name:, version_grouping: :default)
+        validate_inputs!(records, values_by_field_name, version_grouping)
+
+        records = records.to_a
+        return { successes: [], errors_by_record: {} } if records.empty?
+
+        validate_record_classes!(host_class, records)
+
+        effective_grouping = resolve_grouping(version_grouping)
+        vbn = values_by_field_name.transform_keys(&:to_s)
+        field_uuids = effective_grouping == :per_field ? vbn.keys.index_with { SecureRandom.uuid } : nil
+
+        execute_records(records, vbn, effective_grouping, field_uuids)
+      end
+
+      def apply_record_save(record:, vbn:, effective_grouping:, uuids:, accumulator:)
+        push_uuid = case effective_grouping
+                    when :per_record then uuids[:record]
+                    when :per_field  then uuids[:field].values.first
+                    end
+
+        do_save = lambda do
+          record.typed_eav_attributes = vbn.map { |name, value| { name: name, value: value } }
+          stamp_pending_version_group_ids(record, effective_grouping, uuids)
+
+          if record.save
+            accumulator[:successes] << record
+          else
+            accumulator[:errors_by_record][record] = record.errors.messages.transform_keys(&:to_s)
+            raise ActiveRecord::Rollback
+          end
+        end
+
+        if push_uuid
+          TypedEAV.with_context(version_group_id: push_uuid, &do_save)
+        else
+          do_save.call
+        end
+      end
+
+      private
+
+      def execute_records(records, vbn, effective_grouping, field_uuids)
+        successes = []
+        errors_by_record = {}
+
+        with_bulk_definitions_memo do
+          ActiveRecord::Base.cache do
+            ActiveRecord::Base.transaction do
+              records.each do |record|
+                record_uuid = effective_grouping == :per_record ? SecureRandom.uuid : nil
+
+                ActiveRecord::Base.transaction(requires_new: true) do
+                  apply_record_save(
+                    record: record,
+                    vbn: vbn,
+                    effective_grouping: effective_grouping,
+                    uuids: { record: record_uuid, field: field_uuids },
+                    accumulator: { successes: successes, errors_by_record: errors_by_record },
+                  )
+                end
+              end
+            end
+          end
+        end
+
+        { successes: successes, errors_by_record: errors_by_record }
+      end
+
+      def validate_inputs!(records, values_by_field_name, version_grouping)
+        if records.nil?
+          raise ArgumentError,
+                "bulk_set_typed_eav_values requires an Enumerable of records, got nil"
+        end
+
+        unless values_by_field_name.is_a?(Hash)
+          raise ArgumentError,
+                "bulk_set_typed_eav_values requires a Hash of values_by_field_name, " \
+                "got #{values_by_field_name.class}"
+        end
+
+        valid_grouping = %i[default per_record per_field none]
+        unless valid_grouping.include?(version_grouping)
+          raise ArgumentError,
+                "version_grouping: #{version_grouping.inspect} is not supported. " \
+                "Supported values: #{valid_grouping.map(&:inspect).join(", ")}."
+        end
+
+        return unless %i[per_record per_field].include?(version_grouping) && !TypedEAV.config.versioning
+
+        raise ArgumentError,
+              "version_grouping: #{version_grouping.inspect} was passed but versioning is disabled. " \
+              "Set TypedEAV.config.versioning = true in your initializer, or pass " \
+              "version_grouping: :none to opt out explicitly, or omit the kwarg to silently no-op."
+      end
+
+      def validate_record_classes!(host_class, records)
+        return if records.all?(host_class)
+
+        classes = records.map { |record| record.class.name }.uniq
+        raise ArgumentError,
+              "bulk_set_typed_eav_values expects records of class #{host_class.name} (or its subclasses); " \
+              "got mixed classes: #{classes.join(", ")}"
+      end
+
+      def resolve_grouping(version_grouping)
+        if version_grouping == :default
+          TypedEAV.config.versioning ? :per_record : :none
+        else
+          version_grouping
+        end
+      end
+
+      def with_bulk_definitions_memo
+        prior_memo = Thread.current[:typed_eav_bulk_defs_memo]
+        Thread.current[:typed_eav_bulk_defs_memo] = {}
+        yield
+      ensure
+        Thread.current[:typed_eav_bulk_defs_memo] = prior_memo
+      end
+
+      def stamp_pending_version_group_ids(record, effective_grouping, uuids)
+        return if effective_grouping == :none
+
+        record.typed_values.each do |value|
+          next unless value.new_record? || value.changed?
+
+          uuid = case effective_grouping
+                 when :per_record then uuids[:record]
+                 when :per_field  then uuids[:field][value.field&.name]
+                 end
+          value.pending_version_group_id = uuid if uuid
+        end
+      end
+    end
+  end
+end

data/lib/typed_eav/column_mapping.rb

@@ -44,6 +44,52 @@ module TypedEAV
         @value_column = column_name.to_sym
       end
 
+      # All typed columns this field type stores its value across. Defaults to
+      # `[value_column]` for single-cell types — every built-in field type as
+      # of Phase 04 returns a one-element Array via this default. Phase 05
+      # Currency overrides this to return `[:decimal_value, :string_value]`
+      # (two-cell type: amount + currency code).
+      #
+      # Phase 04 versioning's snapshot logic iterates `value_columns` to build
+      # the jsonb {col_name => value} hash. Phase 04 also fixes the
+      # `Value#_dispatch_value_change_update` filter to use `value_columns.any?`
+      # instead of the singular `value_column` — forward-compatible with
+      # multi-cell types so a Currency change on the second cell alone still
+      # fires the :update event (Scout §3 / Discrepancy D3).
+      #
+      # The default delegates to `value_column` (the singular), so subclasses
+      # that haven't declared `value_column :col_name` raise the same
+      # NotImplementedError they always did when `value_columns` is invoked.
+      # This matches the existing contract — `value_column`'s raise is the
+      # "subclass must declare its column" enforcement; `value_columns`
+      # inherits that enforcement transparently.
+      def value_columns
+        [value_column]
+      end
+
+      # Which physical column this operator acts on. Defaults to `value_column`
+      # for single-cell field types — every built-in type as of Phase 04
+      # inherits the default and returns the same column for every supported
+      # operator.
+      #
+      # Multi-cell field types (Phase 05: Currency) override this to route
+      # different operators to different columns. For example, Currency stores
+      # `{amount, currency}` across `decimal_value` + `string_value`; the
+      # `:eq` operator targets amount (`decimal_value`); the `:currency_eq`
+      # operator targets currency code (`string_value`).
+      #
+      # Called from `QueryBuilder.filter` AFTER the
+      # `supported_operators.include?(operator)` validation gate, so this
+      # method is only invoked with operators the field explicitly supports.
+      # Subclasses overriding for unsupported operators is a programming
+      # error caught by the gate, not by this method.
+      #
+      # The unused `operator` parameter is intentional in the default —
+      # subclasses use it to dispatch.
+      def operator_column(_operator)
+        value_column
+      end
+
       # All operators this field type supports for querying.
       # Subclasses can override to restrict or extend.
       def supported_operators