activefacts-compositions 1.9.17 → 1.9.18

data/lib/activefacts/compositions/docgraph.rb

@@ -1,798 +0,0 @@
-#
-# ActiveFacts Compositions, DocGraph Compositor.
-#
-#       Computes an Document/Semantic Graph schema.
-#
-# Copyright (c) 2017 Factil Pty Ltd. Read the LICENSE file.
-#
-require "activefacts/compositions"
-
-module ActiveFacts
-  module Metamodel
-    class Composite
-      def is_document
-        @isa_document = true
-      end
-
-      def is_document?
-        @isa_document
-      end
-
-      def is_triple
-        @isa_triple = true
-      end
-
-      def is_triple?
-        @isa_triple
-      end
-    end
-  end
-end
-
-module ActiveFacts
-  module Compositions
-    class DocGraph < Compositor
-      MM = ActiveFacts::Metamodel unless const_defined?(:MM)
-      TRIPLE_ANNOTATION = /triple/
-
-      def self.options
-        {
-          nested: ['Boolean', "Compose nested documents"],
-        }.merge(Compositor.options)
-      end
-
-      def initialize constellation, name, options = {}
-        # Extract recognised options:
-        @option_nested = options.delete('nested')
-        super constellation, name, options, 'DocGraph'
-      end
-
-      def generate
-        super
-
-        trace :docgraph_details!, "Generating docgraph composition" do
-          # Make a data structure to help in computing the documents
-          make_candidates
-
-          # Apply any obvious document/graph factors
-          assign_default_docgraph
-
-          # Figure out how best to absorb things to reduce the number of documents
-          optimise_absorption
-
-          # Actually make a Composite object for each document and triple:
-          make_composites
-
-          # If a value type has been mapped to a document, add a property to hold its value
-          inject_value_fields
-
-          # # Inject surrogate keys if the options ask for that
-          # inject_surrogates if @option_surrogates
-
-          # # Remove the un-used absorption paths
-          # delete_reverse_absorptions
-
-          # Traverse the absorbed objects to build the path to each required property, including foreign keys:
-          absorb_all_properties
-
-          # Remove mappings for objects we have absorbed
-          clean_unused_mappings
-        end
-
-        trace :docgraph!, "Full #{self.class.basename} composition" do
-          @document_composites.values.sort_by{|composite| composite.mapping.name}.each do |composite|
-            composite.show_trace
-          end
-          @triple_composites.values.sort_by{|composite| composite.mapping.name}.each do |composite|
-            composite.show_trace
-          end
-        end
-      end
-
-      def make_candidates
-        @candidates = @binary_mappings.inject({}) do |hash, (absorption, mapping)|
-          hash[mapping.object_type] = Candidate.new(self, mapping)
-          hash
-        end
-      end
-
-      def assign_default_docgraph
-        trace :docgraph_defaults!, "Preparing DocGraph composition by setting default assumptions" do
-          @candidates.each do |object_type, candidate|
-            candidate.assign_default(@composition)
-          end
-        end
-      end
-
-      def optimise_absorption
-        trace :docgraph_optimiser!, "Optimise DocGraph Composition" do
-          undecided = @candidates.keys.select{|object_type| @candidates[object_type].is_tentative}
-          pass = 0
-          finalised = []
-          begin
-            pass += 1
-            trace :docgraph_optimiser, "Starting optimisation pass #{pass}" do
-              finalised = optimise_absorption_pass(undecided)
-            end
-            trace :docgraph_optimiser, "Finalised #{finalised.size} on this pass: #{finalised.map{|f| f.name}*', '}"
-            undecided -= finalised
-          end while !finalised.empty?
-        end
-      end
-
-      def optimise_absorption_pass undecided
-        undecided.select do |object_type|
-          candidate = @candidates[object_type]
-          trace :docgraph_optimiser, "Considering possible status of #{object_type.name}" do
-
-            # Rule 1: Always absorb an objectified unary into its role player (unless its forced to be separate)
-            if !object_type.is_separate && (f = object_type.fact_type) && f.all_role.size == 1
-              absorbing_ref = candidate.mapping.all_member.detect{|a| a.is_a?(MM::Absorption) and a.child_role.base_role == f.all_role.single}
-              raise "REVISIT: Internal error" unless absorbing_ref.parent_role.object_type == object_type
-              absorbing_ref = absorbing_ref.flip!
-              candidate.full_absorption =
-                @constellation.FullAbsorption(composition: @composition, absorption: absorbing_ref, object_type: object_type)
-              trace :docgraph_optimiser, "Fully absorb objectified unary #{object_type.name} into #{f.all_role.single.object_type.name}"
-              candidate.definitely_not_document
-              next object_type
-            end
-
-            # # Rule 2: If the preferred_identifier contains one role only, played by an entity type that can absorb us, do that:
-            # # (Leave pi_roles intact for further use below)
-            # absorbing_ref = nil
-            pi_roles = []
-            # if object_type.is_a?(MM::EntityType) and              # We're an entity type
-            #   pi_roles = object_type.preferred_identifier_roles and     # Our PI
-            #   pi_roles.size == 1 and                                    # has one role
-            #   single_pi_role = pi_roles[0] and                          # that role is
-            #   single_pi_role.object_type.is_a?(MM::EntityType) and      # played by another Entity Type
-            #   absorbing_ref =
-            #     candidate.mapping.all_member.detect do |absorption|
-            #       absorption.is_a?(MM::Absorption) && absorption.child_role.base_role == single_pi_role
-            #     end
-            #
-            #   absorbing_ref = absorbing_ref.forward_absorption || absorbing_ref.flip!
-            #   candidate.full_absorption =
-            #     @constellation.FullAbsorption(composition: @composition, absorption: absorbing_ref, object_type: object_type)
-            #   trace :docgraph_optimiser, "EntityType #{single_pi_role.object_type.name} identifies EntityType #{object_type.name}, so fully absorb it via #{absorbing_ref.inspect}"
-            #   candidate.definitely_not_document
-            #   next object_type
-            # end
-
-            # Rule 3: If there's more than one absorption path and any functional dependencies that can't absorb us, it's a document
-            trace :docgraph_optimiser, "From-references for #{object_type.name}(#{pi_roles.map(&:object_type).map(&:name)*', '}) are #{candidate.references_from.map(&:inspect)*', '}"
-            non_identifying_refs_from =
-              candidate.references_from.reject do |member|
-                case member
-                when MM::Absorption
-                  pi_roles.include?(member.child_role.base_role)
-                when MM::Indicator
-                  pi_roles.include?(member.role)
-                else
-                  false
-                end
-              end
-            trace :docgraph_optimiser, "#{object_type.name} has #{non_identifying_refs_from.size} non-identifying functional roles" do
-              non_identifying_refs_from.each do |a|
-                trace :docgraph_optimiser, a.inspect
-              end
-            end
-
-            trace :docgraph_optimiser, "#{object_type.name} has #{candidate.references_to.size} references to it" do
-              candidate.references_to.each do |a|
-                trace :docgraph_optimiser, a.inspect
-              end
-            end
-
-            # Both of these conditions are not relevant for documents
-            # if candidate.references_to.size > 1 and       # More than one place wants us
-            #     non_identifying_refs_from.size > 0        # And we carry dependent values so cannot be absorbed
-            #   trace :docgraph_optimiser, "#{object_type.name} has #{non_identifying_refs_from.size} non-identifying functional dependencies and #{candidate.references_to.size} absorption paths so it is a document"
-            #   candidate.definitely_document
-            #   next object_type
-            # end
-
-            # At this point, this object either has no functional dependencies or only one place it would be absorbed
-            next false if !candidate.is_document   # We can't reduce the number of tables by absorbing this one
-
-            absorption_paths =
-              ( non_identifying_refs_from +   # But we should exclude any that are already involved in an absorption; pre-decided ET=>ET or supertype absorption!
-                candidate.references_to       # These are our reverse absorptions that could absorb us
-              ).select do |a|
-                next false unless a.is_a?(MM::Absorption)   # Skip Indicators, we can't be absorbed there
-                child_candidate = @candidates[a.child_role.object_type]
-
-                # It's ok if we absorbed them already
-                next true if a.full_absorption && child_candidate.full_absorption.absorption != a
-
-                # If our counterpart is a full absorption, don't try to reverse that!
-                next false if (aa = (a.forward_absorption || a.reverse_absorption)) && aa.full_absorption
-
-                # Otherwise the other end must already be a document or fully absorbed into one
-                next false unless child_candidate.nil? || child_candidate.is_document || child_candidate.full_absorption
-
-                next false unless a.child_role.is_unique && a.parent_role.is_unique   # Must be one-to-one
-
-                # next true if pi_roles.size == 1 && pi_roles.include?(a.parent_role) # Allow the sole identifying role for this object
-                next false unless a.parent_role.is_mandatory # Don't absorb an object along a non-mandatory role
-                true
-              end
-
-            trace :docgraph_optimiser, "#{object_type.name} has #{absorption_paths.size} absorption paths"
-
-            # # Rule 4: If this object can be fully absorbed along non-identifying roles, do that (maybe flip some absorptions)
-            # if absorption_paths.size > 0
-            #   trace :docgraph_optimiser, "#{object_type.name} is fully absorbed in #{absorption_paths.size} places" do
-            #     absorption_paths.each do |a|
-            #       a = a.flip! if a.forward_absorption
-            #       trace :docgraph_optimiser, "#{object_type.name} is fully absorbed via #{a.inspect}"
-            #     end
-            #   end
-            #
-            #   candidate.definitely_not_document
-            #   next object_type
-            # end
-
-            # Rule 5: If this object has no functional dependencies (only its identifier), it can be absorbed in multiple places
-            # We don't create FullAbsorptions, because they're only used to resolve references to this object; and there are none here
-            refs_to = candidate.references_to.reject{|a|a.parent_role.base_role.is_identifying}
-            if !refs_to.empty? and non_identifying_refs_from.size == 0
-              refs_to.map! do |a|
-                a = a.flip! if a.reverse_absorption   # We were forward, but the other end must be
-                a.forward_absorption
-              end
-              trace :docgraph_optimiser, "#{object_type.name} is fully absorbed in #{refs_to.size} places: #{refs_to.map{|ref| ref.inspect}*", "}"
-              candidate.definitely_not_document
-              next object_type
-            end
-
-            false   # Otherwise we failed to make a decision about this object type
-          end
-        end
-      end
-
-      def top component
-        component.parent ? top(component.parent) : component
-      end
-
-      # Remove the unused reverse absorptions:
-      def delete_reverse_absorptions
-        # @binary_mappings.each do |object_type, mapping|
-        #   mapping.all_member.to_a.              # Avoid problems with deletion from all_member
-        #   each do |member|
-        #     next unless member.is_a?(MM::Absorption)
-        #     next unless member.forward_absorption
-        #     # retract if this absorption is not in a document or the forward absorption is in a document
-        #     member.retract if @document_composites[top(member.forward_absorption).object_type] || !@document_composites[top(member).object_type]
-        #   end
-        #   mapping.re_rank
-        # end
-      end
-
-      # After all document/triple decisions are made, convert Mappings for triples into Composites and retract the rest:
-      def make_composites
-        @document_composites = {}
-        @triple_composites = {}
-        @candidates.keys.to_a.each do |object_type|
-          candidate = @candidates[object_type]
-
-          if (candidate.is_document or candidate.is_triple) and !candidate.is_tentative
-            make_composite(candidate)
-          else
-            @candidates.delete(object_type)
-          end
-        end
-      end
-
-      def make_composite candidate
-        mapping = candidate.mapping
-        composite = @constellation.Composite(mapping, composition: @composition)
-        if candidate.is_document
-          @document_composites[mapping.object_type] = composite
-          composite.is_document
-        else
-          @triple_composites[mapping.object_type] = composite
-          composite.is_triple
-        end
-      end
-
-      # Inject a ValueField for each value type that is a document:
-      def inject_value_fields
-        @document_composites.each do |key, composite|
-          mapping = composite.mapping
-          if mapping.object_type.is_a?(MM::ValueType) and               # Composite needs a ValueField
-              !mapping.all_member.detect{|m| m.is_a?(MM::ValueField)}   # And don't already have one
-            trace :docgraph_properties, "Adding value field for #{mapping.object_type.name}"
-            @constellation.ValueField(
-              :new,
-              parent: mapping,
-              name: mapping.object_type.name+" Value",
-              object_type: mapping.object_type
-            )
-            mapping.re_rank
-          end
-        end
-      end
-
-      def clean_unused_mappings
-        @candidates.keys.to_a.each do |object_type|
-          candidate = @candidates[object_type]
-          next if candidate.is_document or candidate.is_triple
-          mapping = candidate.mapping
-          mapping.retract
-          @binary_mappings.delete(object_type)
-        end
-      end
-
-      def is_empty_inheritance mapping
-        # Cannot be an empty inheritance unless it's an TypeInheritance absorption
-        return false if !mapping.is_a?(MM::Absorption) || !mapping.parent_role.fact_type.is_a?(MM::TypeInheritance)
-
-        # It's empty if it's a TypeInheritance which has no non-empty members
-        !mapping.all_member.to_a.any? do |member|
-          !is_empty_inheritance(member)
-        end
-      end
-
-      def elide_empty_inheritance mapping
-        mapping.all_member.to_a.each do |member|
-          if member.is_a?(MM::Absorption) && member.parent_role.fact_type.is_a?(MM::TypeInheritance)
-            elide_empty_inheritance(member)
-            if member.all_member.size == 0
-              trace :docgraph, "Retracting empty inheritance #{member.inspect}"
-              member.retract
-            end
-          end
-        end
-      end
-
-      # Absorb all items which aren't documents (and keys to those which are) recursively
-      def absorb_all_properties
-        trace :docgraph_properties!, "Computing contents of all documents and triples" do
-          @document_composites.values.sort_by{|composite| composite.mapping.name}.each do |composite|
-            trace :docgraph_properties, "Computing contents of #{composite.mapping.name}" do
-              absorb_all(composite.mapping, composite.mapping)
-            end
-          end
-        end
-      end
-
-      #
-      # Rename parents functions defined because they are used in both Staging and Datavault subclasses
-      #
-      def apply_name pattern, name
-        pattern.sub(/\+/, name)
-      end
-
-      def rename_parents
-        @document_composites.each do |key, composite|
-          composite.mapping.name = apply_name(@option_stg_name, composite.mapping.name)
-        end
-      end
-
-      # This member is an Absorption. Process it recursively, either absorbing all its members if it is not a document,
-      # deleting it if it is a semantic triple or just keeping the key if it is not a semantic triple
-      def absorb_subdoc mapping, member, paths, stack
-        trace :docgraph_properties, "Absorb subdoc of #{member.inspect} into #{mapping.name}" do
-          # In the DocGraph composition, either absorb the contents or devolve a triple
-          trace :docgraph_properties, "(parent #{member.parent_role.object_type.name}, child #{member.child_role.object_type.name})"
-          child_object_type = member.child_role.object_type
-          child_mapping = @binary_mappings[child_object_type]
-          if @triple_composites[child_object_type]
-            trace :docgraph_triple, "Eliminate #{child_object_type.name} subdoc"
-            member.retract
-            mapping.re_rank
-            return
-          end
-
-          # Is our target object_type fully absorbed (and not through this absorption)?
-          full_absorption = child_object_type.all_full_absorption[@composition]
-          # We can't use member.full_absorption here, as it's not populated on forked copies
-          # if full_absorption && full_absorption != member.full_absorption
-          if full_absorption && full_absorption.absorption.parent_role.fact_type != member.parent_role.fact_type
-
-            # REVISIT: This should be done by recursing to absorb_key, not using a loop
-            absorption = member   # Retain this for the ForeignKey
-            begin     # Follow transitive target absorption
-              member = mirror(full_absorption.absorption, member)
-              child_object_type = full_absorption.absorption.parent_role.object_type
-            end while full_absorption = child_object_type.all_full_absorption[@composition]
-            child_mapping = @binary_mappings[child_object_type]
-
-            trace :docgraph_properties, "Absorbing all of #{member.child_role.name} in #{member.inspect_reading}"
-            absorb_all(member, child_mapping, paths, stack)
-            return
-          end
-
-          absorb_all(member, child_mapping, paths, stack)
-        end
-      end
-
-      # Handle the reverse absorptions of the mapping
-      def absorb_nested mapping, member, paths, stack
-        trace :docgraph_properties, "Absorb nested of #{member.inspect} into #{mapping.name}" do
-          # In the DocGraph composition, either absorb the contents or devolve a triple
-          if @triple_composites[member.child_role.object_type]
-            trace :docgraph_triple, "Handle #{member.inspect} as a semantic triple"
-            member.retract
-            mapping.re_rank
-            return
-          end
-
-          # This is a nested structure, annotate as Nested, flip the member and absorb all
-          @constellation.Nesting(member, 0, index_role: member.child_role)
-
-          # member.flip!
-          child_object_type = member.child_role.object_type
-          child_mapping = @binary_mappings[child_object_type]
-          absorb_all(member, child_mapping, paths, stack)
-        end
-      end
-
-      # May be overridden in subclasses
-      def prefer_natural_key building_natural_key, source_composite, target_composite
-        false
-      end
-
-      # Augment the mapping with copies of the children of the "from" mapping.
-      # At the top level, no "from" is given and the children already exist
-      def absorb_all mapping, from, paths = {}, stack = []
-        trace :docgraph_properties, "Absorbing all from #{from.inspect} into #{mapping.name}" do
-          top_level = mapping == from
-
-          pcs = []
-          newpaths = {}
-          if mapping.composite || mapping.full_absorption
-            pcs = find_uniqueness_constraints(mapping)
-
-            # Don't build an index from the same PresenceConstraint twice on the same composite (e.g. for a subtype)
-            existing_pcs = mapping.root.all_access_path.select{|ap| MM::Index === ap}.map(&:presence_constraint)
-            newpaths = make_new_paths(mapping, paths.keys+existing_pcs, pcs)
-          end
-
-          from.re_rank
-          substack = stack + [from.object_type]
-          ordered = from.all_member.sort_by(&:ordinal)
-          ordered.each do |member|
-            trace :docgraph_properties, "... considering #{member.child_role.object_type.name}"
-
-            # Only proceed if there is no absorption loop and we are not jumping to another document
-            if !absorption_loop(member, substack) && !@document_composites[member.child_role.object_type]
-              unless top_level    # Top-level members are already instantiated
-                member = member.fork_to_new_parent(mapping)
-              end
-              rel = paths.merge(relevant_paths(newpaths, member))
-              augment_paths(rel, member)
-
-              if member.is_a?(MM::Absorption) && !member.forward_absorption && member.parent_role.is_unique && member.child_role.object_type.is_a?(MM::EntityType)
-                # Only forward absorptions here please...
-                absorb_subdoc(mapping, member, rel, substack)
-              elsif member.is_a?(MM::Absorption) && (member.forward_absorption || !member.parent_role.is_unique) # && top_level
-                absorb_nested(mapping, member, rel, substack)
-              end
-            end
-          end
-
-          # Clean up if mapping does not have any members
-          if mapping.all_member.size == 0
-            mapping_parent = mapping.parent
-            mapping.retract
-            mapping_parent.re_rank
-          end
-
-          newpaths.values.select{|ix| ix.all_index_field.size == 0}.each(&:retract)
-        end
-      end
-
-      def absorption_loop(absorption, stack)
-        trace :docgraph_properties, "Stack is #{stack.map{|ot| ot.name} * ', '}"
-        result = stack.any? {|ot| ot == absorption.child_role.object_type}
-        trace :docgraph_properties, "absorption child is #{absorption.child_role.object_type.name}, loop is #{result}"
-        result
-      end
-
-      # Find all PresenceConstraints to index the object in this Mapping
-      def find_uniqueness_constraints mapping
-        return [] unless mapping.object_type.is_a?(MM::EntityType)
-
-        start_roles =
-            mapping.
-            object_type.
-            all_role_transitive.        # Includes objectification roles for objectified fact types
-            select do |role|
-              (role.is_unique ||                # Must be unique on near role
-                role.fact_type.is_unary) &&     # Or be a unary role
-              !(role.fact_type.is_a?(MM::TypeInheritance) && role == role.fact_type.supertype_role) # allow roles as subtype
-            end.
-            map(&:counterpart).         # (Same role if it's a unary)
-            compact.                    # Ignore nil counterpart of a role in an n-ary
-            map(&:base_role).           # In case it's a link fact type
-            uniq
-
-        pcs =
-          start_roles.
-          flat_map(&:all_role_ref).     # All role_refs
-          map(&:role_sequence).         # The role_sequence
-          uniq.
-          flat_map(&:all_presence_constraint).
-          uniq.
-          reject do |pc|
-            pc.max_frequency != 1 ||    # Must be unique
-            pc.enforcement ||           # and alethic
-            pc.role_sequence.all_role_ref.detect do |rr|
-              !start_roles.include?(rr.role)    # and span only valid roles
-            end ||                      # and not be the full absorption path
-            (   # Reject a constraint that caused full absorption
-              pc.role_sequence.all_role_ref.size == 1 and
-              mapping.is_a?(MM::Absorption) and
-              fa = mapping.full_absorption and
-              pc.role_sequence.all_role_ref.single.role.base_role == fa.absorption.parent_role.base_role
-            )
-          end  # Alethic uniqueness constraint on far end
-
-        non_absorption_pcs = pcs.reject do |pc|
-          # An absorption PC is a PC that covers some role that is involved in a FullAbsorption
-          full_absorptions =
-            pc.
-            role_sequence.
-            all_role_ref.
-            map(&:role).
-            flat_map do |role|
-              (role.all_absorption_as_parent_role.to_a + role.all_absorption_as_child_role.to_a).
-                select do |abs|
-                  abs.full_absorption && abs.full_absorption.composition == @composition
-                end
-            end
-          full_absorptions.size > 0
-        end
-        pcs = non_absorption_pcs
-
-        trace :docgraph_paths, "Uniqueness Constraints for #{mapping.object_type.name}" do
-          pcs.each do |pc|
-            trace :docgraph_paths, "#{pc.describe.inspect}#{pc.is_preferred_identifier ? ' (PI)' : ''}"
-          end
-        end
-
-        pcs
-      end
-
-      def make_new_paths mapping, existing_pcs, pcs
-        newpaths = {}
-        new_pcs = pcs-existing_pcs
-        trace :docgraph_paths, "Adding #{new_pcs.size} new indices for presence constraints on #{mapping.inspect}" do
-          new_pcs.each do |pc|
-            newpaths[pc] = index = @constellation.Index(:new, composite: mapping.root, is_unique: true, presence_constraint: pc)
-            if mapping.object_type.preferred_identifier == pc and
-                !@composition.all_full_absorption[mapping.object_type] and
-                !mapping.root.natural_index
-              mapping.root.natural_index = index
-              mapping.root.primary_index ||= index    # Not if we have a surrogate already
-            end
-            trace :docgraph_paths, "Added new index #{index.inspect} for #{pc.describe} on #{pc.role_sequence.all_role_ref.map(&:role).map(&:fact_type).map(&:default_reading).inspect}"
-          end
-        end
-        newpaths
-      end
-
-      def relevant_paths path_hash, component
-        rel = {}  # REVISIT: return a hash subset of path_hash containing paths relevant to this component
-        case component
-        when MM::Absorption
-          role = component.child_role.base_role
-        when MM::Indicator
-          role = component.role
-        else
-          return rel  # Can't participate in an AccessPath
-        end
-
-        path_hash.each do |pc, path|
-          next unless pc.role_sequence.all_role_ref.detect{|rr| rr.role == role}
-          rel[pc] = path
-        end
-        rel
-      end
-
-      def augment_paths paths, mapping
-        return unless MM::Indicator === mapping || MM::ValueType === mapping.object_type
-
-        if MM::ValueField === mapping && mapping.parent.composite   # ValueType that's a composite (table) by itself
-          # This AccessPath has exactly one field and no presence constraint, so just make the index.
-          composite = mapping.parent.composite
-          paths[nil] =
-            index = @constellation.Index(:new, composite: mapping.root, is_unique: true, presence_constraint: nil, composite_as_natural_index: composite)
-          composite.primary_index ||= index
-        end
-
-        paths.each do |pc, path|
-          trace :docgraph_paths, "Adding access path #{mapping.inspect} to #{path.inspect}" do
-            case path
-            when MM::Index
-              @constellation.IndexField(access_path: path, ordinal: path.all_index_field.size, component: mapping)
-            when MM::ForeignKey
-              @constellation.ForeignKeyField(foreign_key: path, ordinal: path.all_foreign_key_field.size, component: mapping)
-            end
-          end
-        end
-      end
-
-      # Make a new Absorption in the reverse direction from the one given
-      def mirror absorption, parent
-        @constellation.fork(
-          absorption,
-          guid: :new,
-          object_type: absorption.parent_role.object_type,
-          parent: parent,
-          parent_role: absorption.child_role,
-          child_role: absorption.parent_role,
-          ordinal: 0,
-          name: role_name(absorption.parent_role)
-        )
-      end
-
-      # A candidate is a Mapping of an object type which may become a Composition (a table, in docgraph-speak)
-      class Candidate
-        attr_reader :mapping, :is_document, :is_triple, :is_tentative
-        attr_accessor :full_absorption
-
-        def initialize compositor, mapping
-          @compositor = compositor
-          @mapping = mapping
-        end
-
-        def object_type
-          @mapping.object_type
-        end
-
-        # References from us are things we can own (non-Mappings) or have a unique forward absorption for
-        def references_from
-          @mapping.all_member.select{|m| !m.is_a?(MM::Absorption) or !m.forward_absorption && m.parent_role.is_unique }
-        end
-        alias_method :rf, :references_from
-
-        # References to us are reverse absorptions where the forward absorption can absorb us
-        def references_to
-          @mapping.all_member.select{|m| m.is_a?(MM::Absorption) and f = m.forward_absorption and f.parent_role.is_unique}
-        end
-        alias_method :rt, :references_to
-
-        def has_references
-          @mapping.all_member.select{|m| m.is_a?(MM::Absorption) }
-        end
-
-        def definitely_not_document
-          @is_tentative = @is_document = false
-        end
-
-        def definitely_document
-          @is_tentative = false
-          @is_document = true
-          @is_triple = false
-        end
-
-        def definitely_not_triple
-          @is_tentative = @is_triple = false
-        end
-
-        def definitely_triple
-          @is_tentative = false
-          @is_triple = true
-          @is_document = false
-        end
-
-        def probably_not_document
-          @is_tentative = true
-          @is_document = false
-        end
-
-        def probably_document
-          @is_tentative = @is_document = true
-        end
-
-        def assign_default composition
-          o = object_type
-          if o.is_separate
-            trace :docgraph_defaults, "#{o.name} is a document because it's declared independent or separate"
-            definitely_document
-            return
-          end
-
-          if o.concept.all_concept_annotation.detect{|ca| ca.mapping_annotation =~ TRIPLE_ANNOTATION}
-            trace :docgraph_defaults, "#{o.name} is a triple because it's declared triple"
-            definitely_triple
-            return
-          end
-
-          case o
-          when MM::ValueType
-            if o.is_auto_assigned
-              trace :docgraph_defaults, "#{o.name} is not a document because it is auto assigned"
-              definitely_not_document
-            elsif references_from.size > 0
-              trace :docgraph_defaults, "#{o.name} is a document because it has references to absorb"
-              definitely_document
-            else
-              trace :docgraph_defaults, "#{o.name} is not a document because it will be absorbed wherever needed"
-              definitely_not_document
-            end
-
-          when MM::EntityType
-            if references_to.empty? and
-                !references_from.detect do |absorption|   # detect whether anything can absorb this entity type
-                  absorption.is_a?(MM::Mapping) && absorption.parent_role.is_unique # DG && absorption.child_role.is_unique
-                end
-              trace :docgraph_defaults, "#{o.name} is a document because it has nothing to absorb it"
-              definitely_document
-              return
-            end
-
-            # its a triple if this is an objectified fact type that has a uniqueness constraint of size = 2
-            if o.fact_type
-              # List the UCs on this fact type:
-              all_uniqueness_constraints =
-                o.fact_type.all_role.map do |fact_role|
-                  fact_role.all_role_ref.map do |rr|
-                    rr.role_sequence.all_presence_constraint.select { |pc| pc.max_frequency == 1 }
-                  end
-                end.flatten.uniq
-
-              if all_uniqueness_constraints.detect do |uc|
-                  (arr = uc.role_sequence.all_role_ref).size == 2 and arr[0].role.object_type.is_a?(MM::EntityType) and arr[1].role.object_type.is_a?(MM::EntityType)
-                end
-                trace :docgraph_defaults, "#{o.name} is a triple because is an objectified fact type with uniqueness contraint of 2"
-                definitely_triple
-                return
-              end
-            end
-
-            if !o.supertypes.empty?
-              # We know that this entity type is not a separate or partitioned subtype, so a supertype that can absorb us does
-              identifying_fact_type = o.all_type_inheritance_as_subtype.detect{|ti| ti.provides_identification}
-              if identifying_fact_type
-                fact_type = identifying_fact_type
-              else
-                if o.all_type_inheritance_as_subtype.size > 1
-                  trace :docgraph_defaults, "REVISIT: #{o.name} cannot be absorbed into a supertype that doesn't also absorb all our other supertypes (or is absorbed into one of its supertypes that does)"
-                end
-                fact_type = o.all_type_inheritance_as_subtype.to_a[0]
-              end
-
-              absorbing_ref = mapping.all_member.detect{|m| m.is_a?(MM::Absorption) && m.child_role.fact_type == fact_type}
-
-              absorbing_ref = absorbing_ref.flip! if absorbing_ref.reverse_absorption   # We were forward, but the other end must be
-              absorbing_ref = absorbing_ref.forward_absorption
-              self.full_absorption =
-                o.constellation.FullAbsorption(composition: composition, absorption: absorbing_ref, object_type: o)
-              trace :docgraph_defaults, "Supertype #{fact_type.supertype_role.name} fully absorbs subtype #{o.name} via #{absorbing_ref.inspect}"
-              definitely_not_document
-              return
-            end # subtype
-
-            # If the preferred_identifier consists of a ValueType that's auto-assigned,
-            # that can only happen in one document, which controls the sequence.
-            auto_assigned_identifying_role_player = nil
-            pi_role_refs = o.preferred_identifier.role_sequence.all_role_ref
-            if pi_role_refs.size == 1 and
-                rr = pi_role_refs.single and
-                (v = rr.role.object_type).is_a?(MM::ValueType) and
-                v.is_auto_assigned == 'commit'
-              auto_assigned_identifying_role_player = v
-            end
-            if (@compositor.options['single_sequence'] || references_to.size > 1) and auto_assigned_identifying_role_player   # Can be absorbed in more than one place
-              trace :docgraph_defaults, "#{o.name} must be a document to support its auto-assigned identifier #{auto_assigned_identifying_role_player.name}"
-              definitely_document
-              return
-            end
-
-            trace :docgraph_defaults, "#{o.name} is initially presumed to be a document"
-            probably_document
-
-          end   # case
-        end
-
-      end
-
-    end
-
-    publish_compositor(DocGraph)
-  end
-end