typed_eav 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 392d8c372c1b70b4b710cef0b9f67d79531fb237bbca37419906ed468ced365f
-  data.tar.gz: e8d9fd82f5d0d3a2cd894f89090a31522882c0606f28e691be373aacccf73cce
+  metadata.gz: 255a937ce445032caf1880728a75a7363dda1323f8d20650bb2c73380cdb0c82
+  data.tar.gz: 3ff1c84f019c73902ae18812b19e8ab254d30813128f80fc7878adf0b43e21d1
 SHA512:
-  metadata.gz: 0fa26b021b7d5223f1af10e016dad89c546102f8f807d00fa6d3ea8d07a95a3e91948fa67e09137b2d93bb4cba38bf0ed2a91887812a7777fef4821bd87db190
-  data.tar.gz: 195ee963d09d43cb358ff2f39ee4f62bd131cb75fbb110bbe6a00e569c5b693fbd21313e27f899e492edc9ebb921a1021bd432aa754059df4f609d6fa50cd30a
+  metadata.gz: f0dc18a3c981530aba9c5be15acf07a1ce1a766845464aaa656876856f113d2b874e70173e9feb51bc2f88596c6bb9deea8a4b473d058e266c8ebc4e4584689c
+  data.tar.gz: 1d76a14b8ad44f7f17aee8e7973a6a468536711ddfd299cf376cd9d4d41e643c0e84e4b648df1b75bb961cb93764789c9ff9e3c15baffea8f7c323ff64a8f566

data/CHANGELOG.md

@@ -5,6 +5,95 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.6.0] - 2026-07-13
+
+Hardens correctness, query efficiency, installation confidence, and release
+safety while defining the supported runtime window. Existing public method
+signatures and valid-record behavior remain unchanged. The compatibility floor
+is intentionally raised to the release lines exercised by CI.
+
+### Changed
+
+- Define the supported runtime contract as Ruby 3.3–4.0, Rails 7.2–8.1, and
+  PostgreSQL 15–18. Runtime dependency bounds now reject unverified future
+  Ruby and Rails release lines; prereleases remain outside the support
+  guarantee. Issue #26.
+
+### Fixed
+
+- Prevent single-value reads from returning a stale value from a losing
+  partition, and enforce the parent-scope partition invariant in PostgreSQL.
+  Issues #22 and #23.
+- Exercise packaged migrations in a generated Rails consumer application so
+  missing or non-idempotent installation paths fail before release. Issue #25.
+
+### Performance
+
+- Remove obsolete option-cache invalidation and batch-load fields for already
+  loaded typed values. Issues #28 and #29.
+- Bound scaffold visibility queries and preload existing values during default
+  backfills. Issues #30 and #31.
+- Keep all-partitions filter unions inside SQL and batch schema-import lookups
+  and option writes. Issues #32 and #33.
+
+### Documentation
+
+- Refresh maintainer, schema, and architecture guidance for the 0.5+ behavior
+  and current database invariants. Issue #34.
+
+### Release engineering
+
+- Gate trusted publishing on the exact dereferenced tag commit, the complete
+  supported compatibility matrix, lint, package-content inspection, and a
+  real-host migration installation using the same checksummed gem artifact
+  that is sent to RubyGems. Issue #27.
+
+### References
+
+- Issues #22, #23, and #25–#34.
+
+## [0.5.0] - 2026-06-01
+
+Adds a human display label for fields, distinct from the immutable machine
+slug `name` (issue #21). Fully additive — every change defaults to the
+pre-0.5.0 behavior. Existing rows (with `label` NULL) render exactly as
+before, and consumers that never set a label observe no difference.
+
+### Added
+
+- `label` — a nullable, free-text column on `typed_eav_fields`
+  (`20260507000000_add_label_to_typed_eav_fields.rb`). No index, no
+  default, no backfill: `label` never participates in uniqueness, lookup,
+  partitioning, or ordering, so an index would be dead weight. Run
+  `rails typed_eav:install:migrations` (or copy the migration) and migrate
+  to pick it up. `name` stays the immutable machine key.
+
+- `TypedEAV::Field::Base#display_name` — the canonical human-facing
+  display string. Returns the free-text `label` when present, otherwise
+  falls back to `name.humanize`. A blank (`""`) label falls back too (via
+  `presence`). This is the ONE accessor all rendering should use; existing
+  rows render unchanged.
+
+- `SchemaPortability` round-trips the label. `export_schema` emits the
+  **raw** `"label"` so `import_schema` reproduces it verbatim and
+  divergence detection treats a differing label as a difference; legacy
+  payloads with no `"label"` key import as NULL with no version gate.
+  `export_snapshot_schema` emits the **resolved** `"display_name"` instead
+  (render-oriented snapshots hand the consumer a ready-to-render string —
+  intentionally asymmetric to the raw-label regular export).
+
+### Changed
+
+- A label-only edit on a Field dispatches the `:update` event, not
+  `:rename`. `:rename` remains reserved for changes to the machine `name`.
+  Regression-pinned in `spec/regressions/issue_21_label_no_rename_spec.rb`.
+
+### References
+
+- Issue #21 — Field display label / `display_name` contract.
+
 ## [0.4.0] - 2026-05-26
 
 Closes four follow-up gaps (PRD #15) surfaced when a downstream Rails app
@@ -338,6 +427,7 @@ worked examples.
 
 Initial release.
 
+[0.6.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.6.0
 [0.3.2]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.2
 [0.3.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.1
 [0.3.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.0

data/README.md

@@ -27,6 +27,22 @@ WHERE integer_value = 42
 
 Standard B-tree indexes work. Range scans work. The query planner is happy. ActiveRecord handles all type casting automatically through the column's registered type.
 
+## Compatibility
+
+The canonical support contract lives in
+[`.github/compatibility.json`](.github/compatibility.json). Typed EAV supports:
+
+| Runtime | Supported versions |
+|---|---|
+| Ruby | 3.3 through 4.0 (`>= 3.3`, `< 4.1`) |
+| Rails | 7.2 through 8.1 (`>= 7.2`, `< 8.2`) |
+| PostgreSQL | 15 through 18 |
+
+CI proves representative floor, middle, and ceiling combinations rather than
+every Cartesian product. Versions outside these ranges and prerelease versions
+are outside the support guarantee. PostgreSQL compatibility claims assume the
+current minor release for each supported major version.
+
 ## Installation
 
 Add to your Gemfile:
@@ -810,6 +826,7 @@ A few non-obvious contracts worth knowing about up front:
 - **Orphan-parent rows rejected**: a `Field` or `Section` row with `parent_scope` set but `scope` blank is invalid. The `Value`-side guard rejects cross-`(scope, parent_scope)` writes too.
 - **Event hooks fire from `after_commit`**: the `on_value_change` and `on_field_change` callbacks fire after the database write is durable; their exceptions never break a save. See §"Event hooks" for the full contract.
 - **Versioning is opt-in**: When enabled (`TypedEAV.config.versioning = true` on the gem; `versioned: true` per host), every `:create` / `:update` / `:destroy` event on a Value writes an append-only audit row in `typed_eav_value_versions`. See §"Versioning" for the full contract.
+- **`label` is cosmetic, `name` is the machine key**: A field's optional `label` is free-text human display, independent of the slug `name`. Render via `display_name`, which returns `label` when present else `name.humanize`. `label` has no uniqueness or format constraints (only a 255-char max) and never affects ordering, lookup, partitioning, or rename detection — editing only `label` fires `on_field_change` with `:update`, never `:rename`. Existing rows (`label` NULL) render unchanged. Schema export round-trips the raw `label` (legacy payloads without a `label` key import as NULL); snapshot export carries the resolved `display_name`.
 
 ## Event hooks
 
@@ -1232,16 +1249,19 @@ As of v0.2.0, the paired partial unique indexes cover the three-key partition tu
 
 ## Schema
 
-The gem creates four tables:
+The gem creates five tables:
 
 - `typed_eav_fields` - field definitions (STI, one row per field per entity type)
 - `typed_eav_values` - values (one row per entity per field, with typed columns)
 - `typed_eav_options` - allowed values for select/multi-select fields
 - `typed_eav_sections` - optional UI grouping
+- `typed_eav_value_versions` - opt-in, append-only audit history for Value
+  create, update, and destroy events; it retains durable entity identity even
+  when the live Value row is later removed
 
 ## Architecture
 
-Internal module layout as of 0.3.0. Most consumers never reach for these directly — the public surface is the `has_typed_eav` macro and the instance/class methods it installs — but the split matters if you're extending the gem, debugging an integration, or evaluating it for production. Decisions are anchored by [ADR-0001](docs/adr/0001-collapse-column-mapping-stack.md) through [ADR-0005](docs/adr/0005-keep-phase-six-modules-independent.md).
+Internal module layout as of 0.5.0. Most consumers never reach for these directly — the public surface is the `has_typed_eav` macro and the instance/class methods it installs — but the split matters if you're extending the gem, debugging an integration, or evaluating it for production. Decisions are anchored by [ADR-0001](docs/adr/0001-collapse-column-mapping-stack.md) through [ADR-0006](docs/adr/0006-include-missing-via-set-complement.md).
 
 ### Macro entry: `HasTypedEav`
 
@@ -1313,6 +1333,16 @@ Single-record reads (`typed_eav_value`, `typed_eav_hash`) live on `InstanceMetho
 
 Every method uses `TypedEAV::Partition.definitions_by_name` so the collision-precedence rules for ambient/explicit/parent scopes are computed in one place.
 
+### Partition visibility: `Partition`
+
+Host applications that need to inspect effective schema should use the
+documented-public `TypedEAV::Partition` seam rather than rebuilding tuple
+predicates. It exposes `visible_fields`, `effective_fields_by_name`,
+`definitions_by_name`, `definitions_multimap_by_name`, `visible_sections`,
+and `find_visible_section!`. These methods preserve global, scope-only, and
+full-tuple precedence; ADR-0006 additionally fixes include-missing set
+composition at the `FilterQuery` altitude.
+
 ### Field types and storage: `Field::TypedStorage`
 
 `TypedEAV::Field::Base` is the STI parent of every field type. The shared storage surface lives in the `TypedEAV::Field::TypedStorage` concern (`lib/typed_eav/field/typed_storage.rb`, ~200 LOC), auto-included on `Field::Base`. Per [ADR-0001](docs/adr/0001-collapse-column-mapping-stack.md), it provides:

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

@@ -45,6 +45,11 @@ module TypedEAV
 
       validates :name, presence: true, uniqueness: { scope: %i[entity_type scope parent_scope] }
       validates :name, exclusion: { in: RESERVED_NAMES, message: "is reserved" }
+      # `label` is optional free-text human display, independent of the machine
+      # slug `name` (issue #21). The ONLY guard is a max-length sanity bound —
+      # intentionally NO uniqueness and NO format/exclusion constraint. RESERVED_NAMES,
+      # slug-uniqueness, and rename detection all key on :name and never on :label.
+      validates :label, length: { maximum: 255 }, allow_nil: true
       validates :type, presence: true
       validates :entity_type, presence: true
       validate :validate_default_value
@@ -262,6 +267,16 @@ module TypedEAV
         self.class.name.demodulize.underscore
       end
 
+      # Canonical human-facing display string (issue #21). Returns the
+      # free-text `label` when present, otherwise falls back to humanizing the
+      # machine slug `name`. This is the ONE accessor all rendering should use;
+      # `name` stays the immutable machine key. A blank ("") label falls back
+      # too (via `presence`), so existing rows (label NULL) render exactly as
+      # they did before this column existed.
+      def display_name
+        label.presence || name.humanize
+      end
+
       def array_field?
         false
       end
@@ -282,6 +297,8 @@ module TypedEAV
       end
 
       # Kept for backward compatibility but now a no-op since we don't cache.
+      # TypedEAV does not invoke this hook internally; overriding it is not a
+      # supported option-lifecycle extension point.
       def clear_option_cache!
         # no-op
       end
@@ -346,10 +363,17 @@ module TypedEAV
           # surfaces; prior batches stay committed. Caller re-runs idempotently
           # because the per-record skip rule re-checks each entity.
           ActiveRecord::Base.transaction(requires_new: true) do
-            batch.each do |entity|
-              next unless partition_matches?(entity)
-
-              backfill_one(entity, column)
+            eligible = batch.select { |entity| partition_matches?(entity) }
+            existing_by_entity_id = TypedEAV::Value
+                                    .where(
+                                      entity_type: entity_class.polymorphic_name,
+                                      entity_id: eligible.map(&:id),
+                                      field_id: id,
+                                    )
+                                    .index_by(&:entity_id)
+
+            eligible.each do |entity|
+              backfill_one(entity, column, existing_by_entity_id[entity.id])
             end
           end
         end
@@ -581,9 +605,7 @@ module TypedEAV
       #    row created via explicit `value: nil` is still a backfill
       #    candidate per CONTEXT.md).
       #  - row exists with non-nil typed column → skip (idempotence).
-      def backfill_one(entity, column)
-        existing = TypedEAV::Value.where(entity: entity, field_id: id).first
-
+      def backfill_one(entity, column, existing)
         if existing.nil?
           TypedEAV::Value.create!(entity: entity, field: self, value: default_value)
         elsif existing[column].nil?

data/app/models/typed_eav/option.rb

@@ -12,13 +12,5 @@ module TypedEAV
     validates :value, presence: true, uniqueness: { scope: :field_id }
 
     scope :sorted, -> { order(sort_order: :asc, label: :asc, id: :asc) }
-
-    after_commit :clear_field_option_cache
-
-    private
-
-    def clear_field_option_cache
-      field&.clear_option_cache!
-    end
   end
 end

data/db/migrate/20260507000000_add_label_to_typed_eav_fields.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class AddLabelToTypedEAVFields < ActiveRecord::Migration[7.1]
+  # Additive, nullable, free-text display label distinct from the machine
+  # slug `name` (issue #21). No index, no default, no backfill: `label` never
+  # participates in uniqueness, lookup, partitioning, or ordering, so an index
+  # would be dead weight. Reversible via `change` because `add_column`
+  # auto-inverts. Existing rows keep label NULL and render unchanged through
+  # the new `Field#display_name` (label.presence || name.humanize).
+  def change
+    add_column :typed_eav_fields, :label, :string, null: true
+  end
+end

data/db/migrate/20260712000000_enforce_parent_scope_invariant.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class EnforceParentScopeInvariant < ActiveRecord::Migration[7.1]
+  CONSTRAINTS = {
+    typed_eav_fields: :chk_te_fields_parent_scope_requires_scope,
+    typed_eav_sections: :chk_te_sections_parent_scope_requires_scope,
+  }.freeze
+
+  INVARIANT_SQL = <<~SQL.squish.freeze
+    parent_scope IS NULL
+    OR BTRIM(parent_scope) = ''
+    OR (scope IS NOT NULL AND BTRIM(scope) <> '')
+  SQL
+
+  ORPHAN_SQL = <<~SQL.squish.freeze
+    parent_scope IS NOT NULL
+    AND BTRIM(parent_scope) <> ''
+    AND (scope IS NULL OR BTRIM(scope) = '')
+  SQL
+
+  def up
+    assert_no_orphan_parent_rows!
+
+    CONSTRAINTS.each do |table, name|
+      add_check_constraint table, INVARIANT_SQL, name: name, validate: false, if_not_exists: true
+
+      validate_check_constraint table, name: name
+    end
+  end
+
+  def down
+    CONSTRAINTS.each do |table, name|
+      remove_check_constraint table, name: name, if_exists: true
+    end
+  end
+
+  private
+
+  def assert_no_orphan_parent_rows!
+    violations = CONSTRAINTS.keys.filter_map do |table|
+      count = select_value("SELECT COUNT(*) FROM #{quote_table_name(table)} WHERE #{ORPHAN_SQL}").to_i
+      [table, count] if count.positive?
+    end
+    return if violations.empty?
+
+    evidence = violations.map { |table, count| "#{count} #{table} row(s) have parent_scope without scope" }.join("; ")
+    raise ActiveRecord::MigrationError,
+          "Cannot enforce the typed_eav parent-scope invariant: #{evidence}. Repair these rows and retry."
+  end
+end

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

@@ -133,9 +133,7 @@ class TypedEAVController < ApplicationController
   # `TypedEAV.config.scope_resolver` to set the tuple.
   def scoped_fields
     partition = current_partition!
-    return TypedEAV::Field::Base.all if partition[:mode] == :all_partitions
-
-    TypedEAV::Field::Base.where(id: visible_field_ids(partition))
+    TypedEAV::Partition.visible_fields(**partition)
   end
 
   # Resolve the ambient tuple for writes. Mirrors `scoped_fields` semantics:
@@ -183,12 +181,6 @@ class TypedEAVController < ApplicationController
     { 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?
 

data/lib/typed_eav/entity_query.rb

@@ -75,7 +75,15 @@ module TypedEAV
     # short: meaningful only with `:is_null` (Reading A "no non-NULL
     # value," includes no-row hosts), no-op with `:is_not_null`, silently
     # ignored otherwise.
-    def with_field(name, operator_or_value = nil, value = nil, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE, include_missing: false)
+    # rubocop:disable Metrics/ParameterLists -- preserves the public positional and partition keyword API.
+    def with_field(
+      name,
+      operator_or_value = nil,
+      value = nil,
+      scope: UNSET_SCOPE,
+      parent_scope: UNSET_SCOPE,
+      include_missing: false
+    )
       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 }
@@ -84,6 +92,7 @@ module TypedEAV
                end
       where_typed_eav(filter, scope: scope, parent_scope: parent_scope, include_missing: include_missing)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Returns field definitions for this entity type.
     #

data/lib/typed_eav/filter_query.rb

@@ -147,9 +147,7 @@ module TypedEAV
           # field def has a non-NULL value for it. Union the non-missing
           # entity_ids across all per-tenant field defs, then complement at
           # the host level. ADR-0006.
-          non_missing_ids = fields.flat_map do |f|
-            TypedEAV::QueryBuilder.entity_ids(f, :is_not_null, nil).pluck(:entity_id)
-          end.uniq
+          non_missing_ids = union_entity_ids(fields, :is_not_null, nil)
           query.where.not(id: non_missing_ids)
         else
           union_ids = union_entity_ids(fields, spec[:operator], spec[:value])
@@ -168,11 +166,15 @@ module TypedEAV
     end
 
     # OR-across all field_ids that share the same name (across tenants),
-    # while preserving AND between filters via the chained `.where`. Use the
-    # underlying Value scope (`.filter`) and `pluck(:entity_id)` to collapse
-    # to a plain integer array we can union across tenants.
+    # while preserving AND between filters via the chained `.where`. Keep the
+    # union as a composable entity-id subquery so matching IDs never need to
+    # be materialized in Ruby.
     def union_entity_ids(fields, operator, value)
-      fields.flat_map { |f| TypedEAV::QueryBuilder.filter(f, operator, value).pluck(:entity_id) }.uniq
+      fields
+        .map { |field| TypedEAV::QueryBuilder.filter(field, operator, value) }
+        .reduce { |union, relation| union.or(relation) }
+        .distinct
+        .select(:entity_id)
     end
 
     def parse_filter(filter)

data/lib/typed_eav/has_typed_eav/instance_methods.rb

@@ -166,13 +166,14 @@ module TypedEAV
         typed_values.filter_map { |tv| tv.field_id || tv.field&.id }
       end
 
-      # Selects the candidate value for `typed_eav_value`. On a collision,
-      # prefer the row attached to the winning field_id; otherwise fall back
-      # to the first orphan/non-collision candidate.
+      # Selects the candidate value for `typed_eav_value`. When a definition
+      # wins for the current partition, only a row attached to that field_id
+      # may surface. Retained rows from a host's former partition must not be
+      # used as a fallback when the current winner has no value yet.
       def select_winning_value(candidates, winning)
         return candidates.first unless winning
 
-        candidates.detect { |v| (v.field_id || v.field&.id) == winning.id } || candidates.first
+        candidates.detect { |v| (v.field_id || v.field&.id) == winning.id }
       end
 
       # Hash-builder helper for `typed_eav_hash`. When a winner is registered
@@ -234,10 +235,12 @@ module TypedEAV
       # fast without forcing that contract.
       def loaded_typed_values_with_fields
         if typed_values.loaded?
-          # Don't re-query if the caller already preloaded; ensure each value's
-          # field is materialized (fall back to per-row load if the nested
-          # `:field` was not preloaded).
-          typed_values.to_a
+          values = typed_values.to_a
+          missing_fields = values.reject { |value| value.association(:field).loaded? }
+          if missing_fields.any?
+            ActiveRecord::Associations::Preloader.new(records: missing_fields, associations: :field).call
+          end
+          values
         else
           typed_values.includes(:field).to_a
         end

data/lib/typed_eav/partition.rb

@@ -21,13 +21,18 @@ module TypedEAV
       # scope-only rows, and full-tuple rows. Passing mode: :all_partitions is
       # the deliberate admin bypass; it is distinct from `scope: nil`, which
       # means the global partition only.
-      def visible_fields(entity_type:, scope: nil, parent_scope: nil, mode: :partition)
+      def visible_fields(entity_type: nil, scope: nil, parent_scope: nil, mode: :partition)
         validate_mode!(mode)
-        return TypedEAV::Field::Base.where(entity_type: entity_type) if mode == :all_partitions
+        fields = TypedEAV::Field::Base.all
+        fields = fields.where(entity_type: entity_type) if entity_type
+        return fields if mode == :all_partitions
 
         raise ArgumentError, ORPHAN_PARENT_MESSAGE unless ScopeTuple.invariant_satisfied?(scope, parent_scope)
 
-        TypedEAV::Field::Base.for_entity(entity_type, scope: scope, parent_scope: parent_scope)
+        fields.where(
+          scope: [scope, nil].uniq,
+          parent_scope: [parent_scope, nil].uniq,
+        )
       end
 
       # One visible field per name after collision resolution. Most-specific

data/lib/typed_eav/schema_portability/import_index.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module TypedEAV
+  module SchemaPortability
+    class ImportIndex
+      attr_reader :fields, :sections
+
+      def initialize(field_entries, section_entries)
+        @fields = preload_fields(field_entries)
+        @sections = preload_sections(section_entries)
+      end
+
+      def field_identity(field_or_entry)
+        identity(field_or_entry, :name)
+      end
+
+      def section_identity(section_or_entry)
+        identity(section_or_entry, :code)
+      end
+
+      private
+
+      def preload_fields(entries)
+        return {} if entries.empty?
+
+        identity_relation(TypedEAV::Field::Base, entries, :name)
+          .includes(:field_options)
+          .index_by { |field| field_identity(field) }
+      end
+
+      def preload_sections(entries)
+        return {} if entries.empty?
+
+        identity_relation(TypedEAV::Section, entries, :code)
+          .index_by { |section| section_identity(section) }
+      end
+
+      def identity_relation(model, entries, key)
+        relations = entries.uniq { |entry| identity(entry, key) }.map do |entry|
+          model.where(
+            key => entry[key.to_s],
+            entity_type: entry["entity_type"],
+            scope: entry["scope"],
+            parent_scope: entry["parent_scope"],
+          )
+        end
+        relations.reduce { |union, relation| union.or(relation) }
+      end
+
+      def identity(record_or_entry, key)
+        attributes = [key, :entity_type, :scope, :parent_scope]
+        return attributes.map { |attribute| record_or_entry[attribute.to_s] } if record_or_entry.is_a?(Hash)
+
+        attributes.map { |attribute| record_or_entry.public_send(attribute) }
+      end
+    end
+  end
+end

data/lib/typed_eav/schema_portability.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "schema_portability/import_index"
+
 module TypedEAV
   # Export and import field + section definitions for an exact partition
   # tuple. Value rows are intentionally out of scope.
@@ -89,14 +91,18 @@ module TypedEAV
         validate_conflict_policy!(on_conflict)
 
         result = { "created" => 0, "updated" => 0, "skipped" => 0, "unchanged" => 0, "errors" => [] }
+        field_entries = Array(hash["fields"])
+        section_entries = Array(hash["sections"])
 
         TypedEAV::Field::Base.transaction do
-          Array(hash["fields"]).each do |entry|
-            import_field_entry(entry, on_conflict, result)
+          import_index = ImportIndex.new(field_entries, section_entries)
+
+          field_entries.each do |entry|
+            import_field_entry(entry, on_conflict, result, import_index)
           end
 
-          Array(hash["sections"]).each do |entry|
-            import_section_entry(entry, on_conflict, result)
+          section_entries.each do |entry|
+            import_section_entry(entry, on_conflict, result, import_index)
           end
         end
 
@@ -105,7 +111,7 @@ module TypedEAV
 
       private
 
-      # rubocop:disable Metrics/AbcSize -- flat projection is the canonical field export shape.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- flat projection is the canonical field export shape.
       def export_field_entry(field)
         entry = {
           "name" => field.name,
@@ -113,6 +119,12 @@ module TypedEAV
           "entity_type" => field.entity_type,
           "scope" => field.scope,
           "parent_scope" => field.parent_scope,
+          # Raw label (issue #21) — NOT the resolved display_name. The regular
+          # export round-trips the stored value verbatim so import reproduces
+          # it exactly and divergence detection (field_export_row_equal?) treats
+          # a differing label as a difference. Legacy payloads lack this key →
+          # entry["label"] is nil on import → label stays NULL (no version gate).
+          "label" => field.label,
           "required" => field.required,
           "sort_order" => field.sort_order,
           "field_dependent" => field.field_dependent,
@@ -135,7 +147,7 @@ module TypedEAV
 
         entry
       end
-      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Lean per-field projection used by {.export_snapshot_schema}. Mirrors
       # the option-row ordering rule from {.export_field_entry} — sort
@@ -145,6 +157,12 @@ module TypedEAV
         entry = {
           "name" => field.name,
           "field_type_name" => field.field_type_name,
+          # RESOLVED display_name (issue #21), NOT the raw label — snapshots are
+          # render-oriented (CONTEXT decision 3). This is intentionally
+          # asymmetric to the regular export's raw "label": a snapshot consumer
+          # gets the ready-to-render string (label when present, else
+          # name.humanize) without re-deriving it.
+          "display_name" => field.display_name,
           "required" => field.required,
           "sort_order" => field.sort_order,
           "options" => field.options,
@@ -195,13 +213,9 @@ module TypedEAV
               "Supported: #{valid_policies.map { |policy| ":#{policy}" }.join(", ")}."
       end
 
-      def import_field_entry(entry, on_conflict, result)
-        existing = TypedEAV::Field::Base.find_by(
-          name: entry["name"],
-          entity_type: entry["entity_type"],
-          scope: entry["scope"],
-          parent_scope: entry["parent_scope"],
-        )
+      def import_field_entry(entry, on_conflict, result, import_index)
+        identity = import_index.field_identity(entry)
+        existing = import_index.fields[identity]
 
         if existing
           reject_type_swap!(existing, entry)
@@ -221,7 +235,7 @@ module TypedEAV
             result["updated"] += 1
           end
         else
-          create_field!(entry)
+          import_index.fields[identity] = create_field!(entry)
           result["created"] += 1
         end
       end
@@ -247,6 +261,7 @@ module TypedEAV
 
       def overwrite_field!(existing, entry)
         existing.assign_attributes(
+          label: entry["label"],
           required: entry["required"],
           sort_order: entry["sort_order"],
           field_dependent: entry["field_dependent"],
@@ -269,7 +284,7 @@ module TypedEAV
 
       def create_field!(entry)
         field = TypedEAV::Field::Base.create!(entry.except("options_data"))
-        return unless field.optionable?
+        return field unless field.optionable?
 
         Array(entry["options_data"]).each do |option|
           field.field_options.create!(
@@ -278,16 +293,12 @@ module TypedEAV
             sort_order: option["sort_order"],
           )
         end
+        field
       end
 
-      # rubocop:disable Metrics/MethodLength -- mirrors field import for section rows without option replacement.
-      def import_section_entry(entry, on_conflict, result)
-        existing = TypedEAV::Section.find_by(
-          code: entry["code"],
-          entity_type: entry["entity_type"],
-          scope: entry["scope"],
-          parent_scope: entry["parent_scope"],
-        )
+      def import_section_entry(entry, on_conflict, result, import_index)
+        identity = import_index.section_identity(entry)
+        existing = import_index.sections[identity]
 
         if existing
           if section_export_row_equal?(existing, entry)
@@ -309,11 +320,10 @@ module TypedEAV
             result["updated"] += 1
           end
         else
-          TypedEAV::Section.create!(entry)
+          import_index.sections[identity] = TypedEAV::Section.create!(entry)
           result["created"] += 1
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       def raise_divergent_section!(entry)
         raise ArgumentError,

data/lib/typed_eav/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_eav
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - dchuk
@@ -15,14 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +92,8 @@ files:
 - db/migrate/20260501000000_add_cascade_policy_to_typed_eav_fields.rb
 - db/migrate/20260505000000_create_typed_eav_value_versions.rb
 - db/migrate/20260506000001_add_version_group_id_to_typed_eav_value_versions.rb
+- db/migrate/20260507000000_add_label_to_typed_eav_fields.rb
+- db/migrate/20260712000000_enforce_parent_scope_invariant.rb
 - lib/generators/typed_eav/install/install_generator.rb
 - lib/generators/typed_eav/scaffold/scaffold_generator.rb
 - lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb
@@ -151,6 +159,7 @@ files:
 - lib/typed_eav/query_builder.rb
 - lib/typed_eav/registry.rb
 - lib/typed_eav/schema_portability.rb
+- lib/typed_eav/schema_portability/import_index.rb
 - lib/typed_eav/scope_tuple.rb
 - lib/typed_eav/version.rb
 - lib/typed_eav/versioned.rb
@@ -173,14 +182,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Typed custom fields for ActiveRecord models
 test_files: []