expressir 2.4.32 → 2.4.34

data/lib/expressir/express/schema_compare.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Structural diff of two schemata with a machine-applicable patch
+    # (TODO.eengine/07; eeng --compare/--patch semantics, plugin/p11
+    # compare entry). Declarations match by canonical path
+    # `schema.item`; entity attributes get their own sub-deltas at
+    # `schema.item.attribute` carrying types, optionality and
+    # aggregates inside the signature.
+    #
+    # Interfaces are out of scope: the patch target is a flattened
+    # (longform) schema, which has none.
+    module SchemaCompare
+      # `node` carries the revised declaration for :added and :changed
+      # (nil for :removed) so {SchemaPatch.apply} can rebuild.
+      Delta = Struct.new(:op, :path, :node, keyword_init: true)
+
+      # Resolution artifacts and presentation metadata are not part of
+      # a declaration's structure.
+      SIGNATURE_IGNORE = %w[source include_source remarks remark_items
+                            ref base_path file].freeze
+
+      COLLECTIONS = %i[constants types entities subtype_constraints
+                       functions rules procedures].freeze
+
+      NODE_COLLECTION = {
+        "Expressir::Model::Declarations::Constant" => :constants,
+        "Expressir::Model::Declarations::Type" => :types,
+        "Expressir::Model::Declarations::Entity" => :entities,
+        "Expressir::Model::Declarations::SubtypeConstraint" => :subtype_constraints,
+        "Expressir::Model::Declarations::Function" => :functions,
+        "Expressir::Model::Declarations::Rule" => :rules,
+        "Expressir::Model::Declarations::Procedure" => :procedures,
+      }.freeze
+
+      module_function
+
+      def compare(base, revised)
+        COLLECTIONS.flat_map { |collection| collection_deltas(base, revised, collection) }
+      end
+
+      def collection_deltas(base, revised, collection)
+        base_items = index(base, collection)
+        revised_items = index(revised, collection)
+        deltas = (revised_items.keys - base_items.keys).map do |path|
+          Delta.new(op: :added, path: path, node: revised_items[path])
+        end
+        (base_items.keys - revised_items.keys).each do |path|
+          deltas << Delta.new(op: :removed, path: path, node: nil)
+        end
+        (base_items.keys & revised_items.keys).each do |path|
+          old_item = base_items[path]
+          new_item = revised_items[path]
+          next if signature(old_item) == signature(new_item)
+
+          deltas << Delta.new(op: :changed, path: path, node: new_item)
+          next unless new_item.is_a?(Model::Declarations::Entity)
+
+          deltas.concat(attribute_deltas(old_item, new_item, path))
+        end
+        deltas
+      end
+
+      def attribute_deltas(old_item, new_item, path)
+        old_attrs = index_by_id(Array(old_item.attributes))
+        new_attrs = index_by_id(Array(new_item.attributes))
+        deltas = (new_attrs.keys - old_attrs.keys).map do |name|
+          Delta.new(op: :added, path: "#{path}.#{name}",
+                    node: new_attrs[name])
+        end
+        (old_attrs.keys - new_attrs.keys).each do |name|
+          deltas << Delta.new(op: :removed, path: "#{path}.#{name}", node: nil)
+        end
+        (old_attrs.keys & new_attrs.keys).each do |name|
+          next if signature(old_attrs[name]) == signature(new_attrs[name])
+
+          deltas << Delta.new(op: :changed, path: "#{path}.#{name}",
+                              node: new_attrs[name])
+        end
+        deltas
+      end
+
+      def index_by_id(items)
+        items.filter_map { |item| [item.id&.downcase, item] if item.id }.to_h
+      end
+
+      def index(schema, collection)
+        index_by_id(Array(schema.send(collection)))
+          .transform_keys { |key| "#{schema.id.downcase}.#{key}" }
+      end
+
+      def signature(node)
+        strip(node.to_hash)
+      end
+
+      def strip(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, inner), out|
+            next if SIGNATURE_IGNORE.include?(key.to_s)
+
+            out[key] = strip(inner)
+          end
+        when Array then value.map { |inner| strip(inner) }
+        else value
+        end
+      end
+    end
+
+    # Applies {SchemaCompare} deltas to a schema model, returning the
+    # revised schema. The base schema is deep-copied through the
+    # lutaml-model round trip; the input schema is never mutated.
+    module SchemaPatch
+      module_function
+
+      def apply(base, deltas)
+        revised = base.class.from_hash(base.to_hash)
+        item_deltas, attribute_deltas = deltas.partition do |delta|
+          delta.path.split(".").size == 2
+        end
+        item_deltas.each { |delta| apply_item(revised, delta) }
+        # An item-level :added/:changed node already carries the final
+        # attribute list; its sub-deltas are informational only.
+        replaced_ops = %i[added changed].freeze
+        replaced = item_deltas
+          .select { |delta| replaced_ops.include?(delta.op) }
+          .map(&:path)
+        attribute_deltas
+          .reject { |delta| replaced.include?(delta.path.split(".")[0..1].join(".")) }
+          .each { |delta| apply_attribute(revised, delta) }
+        revised
+      end
+
+      def apply_item(schema, delta)
+        item_key = delta.path.split(".").last.downcase
+        collection = if delta.op == :added
+                       schema.send(SchemaCompare::NODE_COLLECTION.fetch(delta.node.class.name))
+                     else
+                       live_collection(schema, item_key)
+                     end
+        return unless collection
+
+        case delta.op
+        when :added then collection << delta.node
+        when :removed then collection.delete_if { |item| key(item) == item_key }
+        when :changed
+          index = collection.index { |item| key(item) == item_key }
+          return unless index
+
+          collection.delete_at(index)
+          collection.insert(index, delta.node)
+        end
+      end
+
+      def apply_attribute(schema, delta)
+        segments = delta.path.split(".")
+        item = SchemaCompare.index_by_id(all_declarations(schema))[segments[1].downcase]
+        return unless item
+
+        attr_key = segments[2]
+        attrs = Array(item.attributes)
+        case delta.op
+        when :added
+          item.attributes = [*attrs, delta.node]
+        when :removed
+          item.attributes = attrs.reject { |attr| key(attr) == attr_key }
+        when :changed
+          index = attrs.index { |attr| key(attr) == attr_key }
+          return unless index
+
+          item.attributes = attrs
+          item.attributes.delete_at(index)
+          item.attributes.insert(index, delta.node)
+        end
+      end
+
+      def live_collection(schema, item_key)
+        SchemaCompare::COLLECTIONS.map { |name| schema.send(name) }
+          .find do |collection|
+          Array(collection).any? { |item| key(item) == item_key }
+        end
+      end
+
+      def all_declarations(schema)
+        SchemaCompare::COLLECTIONS.flat_map { |name| Array(schema.send(name)) }
+      end
+
+      def key(item)
+        item.id&.downcase
+      end
+    end
+  end
+end

data/lib/expressir/express/shtolo.rb

@@ -130,16 +130,20 @@ module Expressir
           schema.interfaces.each do |iface|
             next unless iface.kind == Model::Declarations::Interface::REFERENCE
 
+            iface_schema = iface.schema.is_a?(String) ? iface.schema : iface.schema&.id
+            target = closure[iface_schema&.safe_downcase]
             iface.items.each do |item|
               original = original_name(item, schema)
-              next unless closure[original]&.entities&.find { |e| e.id == original }
+              next unless target&.entities&.find do |e|
+                e.id.safe_downcase == original.safe_downcase
+              end
 
               @reference_entities << original.safe_downcase
             end
           end
         end
 
-        declarations << build_dependent_rule if @reference_entities.any?
+        declarations.concat(build_dependent_declarations) if @reference_entities.any?
 
         Model::Declarations::Schema.new(
           id: @longform_name,
@@ -166,7 +170,18 @@ module Expressir
       # OWN schema's id, and the global map redirects the bare name so
       # declarations from third schemas resolve to the first occurrence.
       def plan_ids(schemas)
-        seen_first = {}      # downcase id => owning schema (first occurrence)
+        # G.NM.1: EVERY clashing declaration is prefixed (the annex
+        # example munges farming_dot_dog AND pet_shows_dot_dog), so the
+        # clash set is computed over the whole population first.
+        counts = Hash.new(0)
+        schemas.each do |schema|
+          all_decls(schema).each do |decl|
+            next unless decl.respond_to?(:id) && decl.id
+
+            counts[decl.id.safe_downcase] += 1
+          end
+        end
+
         global = {}          # downcase id => munged final
         own_by_schema = {}   # schema => {downcase id => final id}
         schemas.each do |schema|
@@ -175,14 +190,11 @@ module Expressir
             next unless decl.respond_to?(:id) && decl.id
 
             key = decl.id.safe_downcase
-            if seen_first.key?(key)
-              final = "#{schema.id.safe_downcase}_dot_#{decl.id}"
-              own[key] = final
-              global[key] = final
-            else
-              seen_first[key] = schema
-              own[key] = decl.id
-            end
+            own[key] = if counts[key] > 1
+                         global[key] = "#{schema.id.safe_downcase}_dot_#{decl.id}"
+                       else
+                         decl.id
+                       end
           end
           own_by_schema[schema] = own
         end
@@ -253,11 +265,20 @@ module Expressir
         current == current.upcase ? new.upcase : new
       end
 
-      # G.1.6: parse-templates keep the annex rule/function verbatim.
-      def build_dependent_rule
+      # G.1.6: parse-templates keep the annex rule/function verbatim;
+      # the pair is emitted together (the rule's WHERE calls the
+      # function, and the prune pass would drop an uncalled function).
+      def build_dependent_declarations
+        snippet = parse_schema_snippet(dependent_template_src)
+        rule = snippet.schemas.first.rules.first
+        fn = snippet.schemas.first.functions.first
+        [rule, fn].compact
+      end
+
+      def dependent_template_src
         list = @reference_entities.map(&:upcase).join(", ")
         union = @reference_entities.join("+")
-        src = <<~EXP
+        <<~EXP
           SCHEMA __dependent__;
           RULE #{DEPENDENT_RULE_NAME} FOR (#{list});
           LOCAL
@@ -270,9 +291,62 @@ module Expressir
           WHERE
             wr1: dependently_instantiated(all_instances, set_of_input_types, previous_in_chain);
           END_RULE;
+
+          FUNCTION dependently_instantiated(
+              set_of_input_instances : SET OF GENERIC:igen;
+              set_of_input_types      : SET OF STRING;
+              previous_in_chain       : LIST OF GENERIC:cgen): BOOLEAN;
+          LOCAL
+            number_of_input_instances : INTEGER;
+            number_of_referring_instances : INTEGER;
+            bag_of_referring_instances : BAG OF GENERIC:igen := [];
+            dependently_instantiated_flag : BOOLEAN;
+            previous_in_chain_plus : LIST OF GENERIC:cgen := [];
+            result : BOOLEAN := true;
+            set_of_types : SET OF STRING := [];
+          END_LOCAL;
+          IF EXISTS(set_of_input_instances) THEN
+            number_of_input_instances := SIZEOF(set_of_input_instances);
+            set_of_input_types := set_of_input_types + 'GENERIC';
+            REPEAT i := 1 TO number_of_input_instances;
+              bag_of_referring_instances := USEDIN(set_of_input_instances[i], '');
+              IF EXISTS(bag_of_referring_instances) THEN
+                number_of_referring_instances := SIZEOF(bag_of_referring_instances);
+                dependently_instantiated_flag := false;
+                REPEAT j := 1 TO number_of_referring_instances;
+                  set_of_types := TYPEOF(bag_of_referring_instances[j]);
+                  IF set_of_types <= set_of_input_types THEN
+                    IF NOT (bag_of_referring_instances[j] IN previous_in_chain) THEN
+                      previous_in_chain_plus := previous_in_chain +
+                                                set_of_input_instances[i];
+                      IF dependently_instantiated([bag_of_referring_instances[j]],
+                                                  set_of_input_types,
+                                                  previous_in_chain_plus) THEN
+                        dependently_instantiated_flag := true;
+                        ESCAPE;
+                      ELSE
+                        SKIP;
+                      END_IF;
+                    END_IF;
+                  ELSE
+                    dependently_instantiated_flag := true;
+                    ESCAPE;
+                  END_IF;
+                END_REPEAT;
+                IF NOT dependently_instantiated_flag THEN
+                  RETURN(false);
+                END_IF;
+              ELSE
+                RETURN(false);
+              END_IF;
+            END_REPEAT;
+          ELSE
+            RETURN(false);
+          END_IF;
+          RETURN(true);
+          END_FUNCTION;
           END_SCHEMA;
         EXP
-        parse_schema_snippet(src).schemas.first.rules.first
       end
 
       def parse_schema_snippet(src)
@@ -295,10 +369,32 @@ module Expressir
         convert_generic_entities!(artifact)
         convert_renamed_attributes!(artifact)
         rewrite_qualified_strings!(artifact)
+        add_provenance_remark!(artifact)
 
         artifact
       end
 
+      # G.1.10: optional embedded provenance remark — if any schema
+      # name is kept in the longform, ALL contributing schemas are
+      # recorded (`schema = <id> [schema_version_id = '<v>'];`, order
+      # insignificant).
+      def add_provenance_remark!(schema)
+        names = closure.values.map(&:id).sort
+        return if names.empty?
+
+        remarks = ["Original 2003 schemas:"] + names.map do |id|
+          contributing = closure.values.find { |s| s.id == id }
+          version = contributing&.version&.id
+          line = "schema = #{id};"
+          line = "schema = #{id} schema_version_id = '#{version}';" if version
+          line
+        end
+        schema.remark_items = [
+          Model::Declarations::RemarkItem.new(id: "provenance", remarks: remarks),
+          *Array(schema.remark_items),
+        ]
+      end
+
       # G.1.9 prune pass: the artifact keeps only what stays visible
       # and reachable. Runs before the stage-2 rewrites so they never
       # see declarations the longform would drop.
@@ -477,57 +573,95 @@ module Expressir
         end
       end
 
+      # G.2.2/G.2.4: every extensible/extending select becomes a
+      # non-extensible select whose items are the full domain in
+      # longform scope. Chains fold in dependency order (a node whose
+      # own BASED_ON is still pending is deferred), so an extending
+      # type that is itself extensible resolves against its base's
+      # folded domain.
+      # G.2.2/G.2.4: every extensible/extending select becomes a
+      # non-extensible select whose items are the full domain in
+      # longform scope. Chains fold in dependency order (a node whose
+      # own BASED_ON is still pending is deferred), so an extending
+      # type that is itself extensible resolves against its base's
+      # folded domain.
       def resolve_extensible_selects!(schema)
-        schema.types.select do |t|
-          t.underlying_type.is_a?(Model::DataTypes::Select) && t.underlying_type.extensible
-        end.each do |base|
-          sel = base.underlying_type
-
-          # all-extenders for GENERIC_ENTITY selects (WG12 requirement,
-          # #32): the extenders are the entity types themselves — fold in
-          # every entity the artifact carries, so the longform select is
-          # complete against the closure. Flags stay as declared: the
-          # extensible/generic-entity markers are part of the shortform's
-          # semantics and are not expressir's to drop.
-          if sel.generic_entity
-            sel.items = schema.entities.map do |e|
-              Model::References::SimpleReference.new(id: e.id)
-            end
-            next
-          end
+        select_types = schema.types.select do |ty|
+          ty.underlying_type.is_a?(Model::DataTypes::Select)
+        end
+        select_types.select { |ty| sel_pending?(ty) }.each do |base|
+          fold_select_node(schema, select_types, base)
+        end
+      end
 
-          extensions = schema.types.select do |t|
-            t.underlying_type.is_a?(Model::DataTypes::Select) &&
-              !t.underlying_type.extensible &&
-              t.underlying_type.based_on&.id&.safe_downcase == base.id.safe_downcase
+      def sel_pending?(select_type)
+        sel = select_type.underlying_type
+        sel.extensible || sel.based_on
+      end
+
+      def fold_select_node(schema, select_types, base_type)
+        sel = base_type.underlying_type
+        return unless sel_pending?(base_type)
+
+        # all-extenders for GENERIC_ENTITY selects (WG12 requirement,
+        # #32): the extenders are the entity types themselves — fold in
+        # every entity the artifact carries, so the longform select is
+        # complete against the closure. Flags stay as declared: the
+        # extensible/generic-entity markers are part of the shortform's
+        # semantics and are not expressir's to drop.
+        if sel.generic_entity && !sel.based_on
+          sel.items = schema.entities.map do |e|
+            Model::References::SimpleReference.new(id: e.id)
           end
-          merged_items = sel.items +
-            extensions.flat_map { |x| x.underlying_type.items }
-          seen_ids = {}
-          uniq = merged_items.select do |item|
-            key = item.id.safe_downcase
-            next false if seen_ids.key?(key) || key.empty?
-
-            seen_ids[key] = true
+          return
+        end
+
+        own_items = Array(sel.items)
+        inherited = []
+        if sel.based_on
+          base_ty = select_types.find do |ty|
+            ty.id&.safe_downcase == sel.based_on&.id&.safe_downcase
           end
-          sel.items = uniq
-          sel.extensible = false
-          sel.based_on = nil
+          fold_select_node(schema, select_types, base_ty) if base_ty && sel_pending?(base_ty)
+          inherited = base_ty ? Array(base_ty.underlying_type.items) : []
+        end
 
-          extensions.each do |ext|
-            keep = ext.underlying_type.items.map { |i| i.id.upcase }
-            exclusions = uniq.reject { |i| keep.include?(i.id.upcase) }
-            base_ref = "#{@longform_name.upcase}.#{base.id.upcase}"
-            ext.underlying_type = Model::DataTypes::Select.new(
-              items: sel.items.map { |i| Model::References::SimpleReference.new(id: i.id) },
+        extenders = select_types.select do |ty|
+          !ty.equal?(base_type) &&
+            ty.underlying_type.based_on&.id&.safe_downcase == base_type.id&.safe_downcase
+        end
+
+        merged = inherited + own_items +
+          extenders.flat_map { |ty| Array(ty.underlying_type.items) }
+        seen = {}
+        uniq = merged.select do |item|
+          key = item.id.safe_downcase
+          next false if key.empty? || seen.key?(key)
+
+          seen[key] = true
+        end
+        sel.items = uniq
+        sel.extensible = false
+        sel.based_on = nil
+
+        extenders.each do |ty|
+          ext_sel = ty.underlying_type
+          keep = Array(ext_sel.items).map { |i| i.id.upcase }
+          base_ref = "#{@longform_name.upcase}.#{base_type.id.upcase}"
+          ty.underlying_type = Model::DataTypes::Select.new(
+            items: uniq.map { |i| Model::References::SimpleReference.new(id: i.id) },
+          )
+          ext_sel_items = ty.underlying_type.items
+          exclusions = uniq.reject { |i| keep.include?(i.id.upcase) }
+          ty.where_rules = exclusions.each_with_index.map do |item, i|
+            Model::Declarations::WhereRule.new(
+              id: "wr#{i + 1}",
+              expression: parse_expression(
+                "NOT ('#{base_ref}.#{item.id.upcase}' IN TYPEOF(SELF));",
+              ),
             )
-            ext.where_rules = exclusions.each_with_index.map do |item, i|
-              Model::Declarations::WhereRule.new(
-                id: "wr#{i + 1}",
-                expression: parse_expression("NOT ('#{base_ref}.#{item.id.upcase}' IN TYPEOF(SELF));"),
-              )
-            end
           end
+          ext_sel_items
         end
       end
 
@@ -543,10 +677,7 @@ module Expressir
             entity.supertype_expression =
               entity.supertype_expression ? combine_andor(entity.supertype_expression, expr) : expr
           end
-          if entity.abstract
-            # G.2.6: abstract entity ⇒ ABSTRACT SUPERTYPE (formatter
-            # renders from abstract + supertype status).
-          end
+          entity.abstract = true if sc.abstract
           next if Array(sc.total_over).empty?
 
           rule_name = "total_over_#{sc.id}"

data/lib/expressir/express.rb

@@ -43,6 +43,8 @@ module Expressir
     autoload :SchemaPlainSourceFormatter,
              "#{__dir__}/express/schema_plain_source_formatter"
     autoload :SchemaSourceFormatter, "#{__dir__}/express/schema_source_formatter"
+    autoload :SchemaCompare, "#{__dir__}/express/schema_compare"
+    autoload :SchemaPatch, "#{__dir__}/express/schema_compare"
     autoload :ScopeResolver, "#{__dir__}/express/scope_resolver"
     autoload :LazyRepository, "#{__dir__}/express/lazy_repository"
     autoload :SmrlXml, "#{__dir__}/express/smrl_xml"

data/lib/expressir/model/declarations/entity.rb

@@ -56,6 +56,138 @@ module Expressir
             *remark_items,
           ]
         end
+
+        # eeng compute-inheritance: the full supertype closure, nearest
+        # supertype first, cycle-safe. Cross-schema supertypes resolve
+        # through the enclosing repository.
+        # @return [Array<Entity>]
+        def supertype_closure
+          closure = []
+          visited = { id&.safe_downcase => true }
+          queue = Array(subtype_of).map { |ref| ref.respond_to?(:id) ? ref.id : ref }
+          while (name = queue.shift)
+            key = name&.safe_downcase
+            next if key.nil? || visited.key?(key)
+
+            supertype = find_supertype_entity(key)
+            next unless supertype
+
+            visited[key] = true
+            closure << supertype
+            queue.concat(Array(supertype.subtype_of).map do |ref|
+              ref.respond_to?(:id) ? ref.id : ref
+            end)
+          end
+          closure
+        end
+
+        # Explicit attributes inherited from the supertype closure,
+        # nearest supertype first, skipping ids this entity (or a
+        # nearer ancestor) redeclares.
+        # @return [Array<ExplicitAttribute>]
+        def inherited_explicit_attributes
+          claimed = explicit_only(Array(attributes)).filter_map(&:id).map(&:safe_downcase)
+          closure = supertype_closure
+          closure.flat_map do |supertype|
+            explicit_only(Array(supertype.attributes)).filter_map do |attr|
+              next nil unless attr.id
+
+              key = attr.id.safe_downcase
+              next nil if claimed.include?(key)
+
+              claimed << key
+              attr
+            end
+          end
+        end
+
+        # Derived attributes accumulated from the supertype closure.
+        # @return [Array<DerivedAttribute>]
+        def inherited_derived_attributes
+          closure = supertype_closure
+          seen = {}
+          closure.flat_map do |supertype|
+            derived_attribute_items(supertype).filter_map do |attr|
+              next nil unless attr.id
+
+              key = attr.id.safe_downcase
+              next nil if seen.key?(key)
+
+              seen[key] = true
+              attr
+            end
+          end
+        end
+
+        # Inverse attributes accumulated from the supertype closure.
+        # @return [Array<InverseAttribute>]
+        def inherited_inverse_attributes
+          closure = supertype_closure
+          seen = {}
+          closure.flat_map do |supertype|
+            inverse_attribute_items(supertype).filter_map do |attr|
+              next nil unless attr.id
+
+              key = attr.id.safe_downcase
+              next nil if seen.key?(key)
+
+              seen[key] = true
+              attr
+            end
+          end
+        end
+
+        # All explicit attributes: own + inherited (eeng
+        # explicit-attrs materialization).
+        # @return [Array<ExplicitAttribute>]
+        def all_explicit_attributes
+          [*explicit_only(Array(attributes)), *inherited_explicit_attributes]
+        end
+
+        private
+
+        # Entity#attributes carries every attribute kind; the explicit
+        # kind is Expressir::Model::Declarations::Attribute.
+        # DerivedAttribute/InverseAttribute subclass Attribute, so the
+        # explicit kind is the exact base class.
+        def explicit_only(attrs)
+          attrs.select { |a| a.instance_of?(Expressir::Model::Declarations::Attribute) }
+        end
+
+        # The Ruby parse path parks every attribute kind in `attributes`
+        # (typed by class); the core path fills derived_attributes/
+        # inverse_attributes instead. Both layouts resolve to the same
+        # items here.
+        def derived_attribute_items(entity)
+          own = Array(entity.derived_attributes)
+          return own if own.any?
+
+          Array(entity.attributes).grep(Expressir::Model::Declarations::DerivedAttribute)
+        end
+
+        def inverse_attribute_items(entity)
+          own = Array(entity.inverse_attributes)
+          return own if own.any?
+
+          Array(entity.attributes).grep(Expressir::Model::Declarations::InverseAttribute)
+        end
+
+        def find_supertype_entity(key)
+          container = parent
+          container = container.parent while container &&
+              !container.is_a?(Model::Repository) &&
+              !container.is_a?(Model::ExpFile)
+          return nil unless container.respond_to?(:schemas)
+
+          container.schemas.each do |foreign|
+            next unless foreign.respond_to?(:entities)
+
+            foreign.entities.each do |candidate|
+              return candidate if candidate.id&.safe_downcase == key
+            end
+          end
+          nil
+        end
       end
     end
   end