activefacts 0.8.6 → 0.8.8

data/lib/activefacts/cql/compiler/entity_type.rb

@@ -0,0 +1,425 @@
+module ActiveFacts
+  module CQL
+    class Compiler < ActiveFacts::CQL::Parser
+
+      class ReferenceMode
+        attr_reader :name, :value_constraint, :parameters
+
+        def initialize name, value_constraint, parameters
+          @name = name
+          @value_constraint = value_constraint
+          @parameters = parameters
+        end
+      end
+
+      class EntityType < Concept
+        def initialize name, supertypes, identification, pragmas, readings
+          super name
+          @supertypes = supertypes
+          @identification = identification
+          @pragmas = pragmas
+          @readings = readings || []
+        end
+
+        def compile
+          @entity_type = @constellation.EntityType(@vocabulary, @name)
+          @entity_type.is_independent = true if (@pragmas.include? 'independent')
+
+          # REVISIT: CQL needs a way to indicate whether subtype migration can occur.
+          # For example by saying "Xyz is a role of Abc".
+          @supertypes.each_with_index do |supertype_name, i|
+            add_supertype(supertype_name, @identification || i > 0)
+          end
+
+          context = CompilationContext.new(@vocabulary)
+
+          # Identification may be via a mode (create it) or by forward-referenced entity types (allow those):
+          prepare_identifier context
+
+          # Create the fact types that define the identifying roles:
+          fact_types = create_identifying_fact_types context
+
+          # At this point, @identification is an array of RoleRefs and/or Readings (for unary fact types)
+          # Have to do this after creating the necessary fact types
+          complete_reference_mode_fact_type fact_types
+
+          # Find the roles to use if we have to create an identifying uniqueness constraint:
+          identifying_roles = bind_identifying_roles context
+
+          make_preferred_identifier_over_roles identifying_roles
+
+          @readings.each do |reading|
+            next unless reading.context_note
+            reading.context_note.compile(@constellation, @entity_type)
+          end
+
+          @entity_type
+        end
+
+        def prepare_identifier context
+          # Figure out the identification mode or roles, if any:
+          if @identification
+            if @identification.is_a? ReferenceMode
+              make_entity_type_refmode_valuetypes(name, @identification.name, @identification.parameters)
+              vt_name = @reference_mode_value_type.name
+              @identification = [Compiler::RoleRef.new(vt_name, nil, nil, nil, nil, nil, @identification.value_constraint, nil)]
+            else
+              context.allowed_forward_terms = legal_forward_references(@identification)
+            end
+          end
+        end
+
+        # Names used in the identifying roles list may be forward referenced:
+        def legal_forward_references(identification_roles)
+          identification_roles.map do |phrase|
+            phrase.is_a?(RoleRef) ? phrase.term : nil
+          end.compact.uniq
+        end
+
+        def bind_identifying_roles context
+          return unless @identification
+          @identification.map do |id|
+            if id.is_a?(RoleRef)
+              id.identify_player(context)
+              binding = id.bind(context)
+              roles = binding.refs.map{|r| r.role}.compact.uniq
+              raise "Looking for an occurrence of identifying role #{id.inspect}, but found #{roles.size == 0 ? "none" : roles.size}" if roles.size != 1
+              roles[0]
+            else
+              # id is a reading of a unary fact type.
+              id.identify_other_players context
+              id.bind_roles context
+              matching_reading =
+                @readings.detect { |reading| reading.phrases_match id.phrases }
+              raise "Unary identifying role 'id.inspect' is not found in the defined fact types" unless matching_reading
+              matching_reading.fact_type.all_role.single
+            end
+          end
+        end
+
+        def make_preferred_identifier_over_roles identifying_roles
+          return unless identifying_roles && identifying_roles.size > 0
+          role_sequence = @constellation.RoleSequence(:new)
+          identifying_roles.each_with_index do |identifying_role, index|
+            @constellation.RoleRef(role_sequence, index, :role => identifying_role)
+          end
+
+          # Find a uniqueness constraint as PI, or make one
+          pc = find_pc_over_roles(identifying_roles)
+          if (pc)
+            pc.is_preferred_identifier = true
+            pc.name = "#{@entity_type.name}PK" unless pc.name
+            debug "Existing PC #{pc.verbalise} is now PK for #{@entity_type.name} #{pc.class.roles.keys.map{|k|"#{k} => "+pc.send(k).verbalise}*", "}"
+          else
+            # Add a unique constraint over all identifying roles
+            pc = @constellation.PresenceConstraint(
+                :new,
+                :vocabulary => @vocabulary,
+                :name => "#{@entity_type.name}PK",            # Is this a useful name?
+                :role_sequence => role_sequence,
+                :is_preferred_identifier => true,
+                :max_frequency => 1              # Unique
+                #:is_mandatory => true,
+                #:min_frequency => 1,
+              )
+          end
+        end
+
+        def find_pc_over_roles(roles)
+          return nil if roles.size == 0 # Safeguard; this would chuck an exception otherwise
+          roles[0].all_role_ref.each do |role_ref|
+            next if role_ref.role_sequence.all_role_ref.map(&:role) != roles
+            pc = role_ref.role_sequence.all_presence_constraint.single  # Will return nil if there's more than one.
+            #puts "Existing PresenceConstraint matches those roles!" if pc
+            return pc if pc
+          end
+          nil
+        end
+
+        def create_identifying_fact_types context
+          fact_types = []
+          # Categorise the readings into fact types according to the roles they play.
+          @readings.each{ |reading| reading.identify_players_with_role_name(context) }
+          @readings.each{ |reading| reading.identify_other_players(context) }
+          @readings.inject({}) do |hash, reading|
+            players_key = reading.role_refs.map{|rr| rr.key.compact}.sort
+            (hash[players_key] ||= []) << reading
+            hash
+          end.each do |players_key, readings|
+            readings.each{ |reading| reading.bind_roles context }  # Create the Compiler::Bindings
+
+            # REVISIT: Loose binding goes here; it might merge some Compiler#Roles
+
+            fact_type = create_identifying_fact_type(context, readings)
+            fact_types << fact_type if fact_type
+            objectify_existing_fact_type(fact_type) unless fact_type.all_role.detect{|r| r.concept == @entity_type}
+          end
+          fact_types
+        end
+
+        def create_identifying_fact_type context, readings
+          # Remove uninteresting assertions:
+          readings.reject!{|reading| reading.is_existential_type }
+          return nil unless readings.size > 0    # Nothing interesting was said.
+
+          # See if any fact type already exists (this ET cannot be a player, but might objectify it)
+          existing_readings = readings.select{ |reading| reading.match_existing_fact_type context }
+          any_matched = existing_readings.size > 0
+
+          operation = any_matched ? 'Objectifying' : 'Creating'
+          player_names = readings[0].role_refs.map{|rr| rr.key.compact*'-'}
+          debug :matching, "#{operation} fact type for #{readings.size} readings over (#{player_names*', '})" do
+            if any_matched  # There's an existing fact type we must be objectifying
+              fact_type = objectify_existing_fact_type(existing_readings[0].fact_type)
+            end
+
+            unless fact_type
+              fact_type = readings[0].make_fact_type(@vocabulary)
+              readings[0].make_reading(@vocabulary, fact_type)
+              readings[0].make_embedded_constraints vocabulary
+              existing_readings = [readings[0]]
+            end
+
+            (readings - existing_readings).each do |reading|
+              reading.make_reading(@vocabulary, fact_type)
+              reading.make_embedded_constraints vocabulary
+            end
+
+            fact_type
+          end
+        end
+
+        def objectify_existing_fact_type fact_type
+          raise "#{@name} cannot objectify fact type '#{fact_type.entity_type.name}' that's already objectified" if fact_type.entity_type
+          raise "#{@name} must only objectify one fact type" if @fact_type
+          if fact_type.internal_presence_constraints.select{|pc| pc.max_frequency == 1}.size == 0
+            # If there's no existing uniqueness constraint over this fact type, make a spanning one.
+            @constellation.PresenceConstraint(
+              :new,
+              :vocabulary => @vocabulary,
+              :name => @entity_type.name+"UQ",
+              :role_sequence => fact_type.preferred_reading.role_sequence,
+              :is_preferred_identifier => false,  # We only get here when there is a reference mode on the entity type
+              :max_frequency => 1
+            )
+          end
+
+          @fact_type = @entity_type.fact_type = fact_type
+          @entity_type.create_implicit_fact_types
+          @fact_type
+        end
+
+        def add_supertype(supertype_name, not_identifying)
+          debug :supertype, "Adding supertype #{supertype_name}" do
+            supertype = @constellation.EntityType(@vocabulary, supertype_name)
+
+            # Did we already know about this supertype?
+            return if @entity_type.all_type_inheritance_as_subtype.detect{|ti| ti.supertype == supertype}
+
+            # By default, the first supertype identifies this entity type
+            is_identifying_supertype = !not_identifying && @entity_type.all_type_inheritance_as_subtype.size == 0
+
+            inheritance_fact = @constellation.TypeInheritance(@entity_type, supertype, :fact_type_id => :new)
+
+            assimilations = @pragmas.select { |p| ['absorbed', 'separate', 'partitioned'].include? p}
+            raise "Conflicting assimilation pragmas #{assimilations*', '}" if assimilations.size > 1
+            inheritance_fact.assimilation = assimilations[0]
+
+            # Create a reading:
+            sub_role = @constellation.Role(inheritance_fact, 0, :concept => @entity_type)
+            super_role = @constellation.Role(inheritance_fact, 1, :concept => supertype)
+
+            rs = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs, 0, :role => sub_role)
+            @constellation.RoleRef(rs, 1, :role => super_role)
+            @constellation.Reading(inheritance_fact, 0, :role_sequence => rs, :text => "{0} is a kind of {1}")
+            # REVISIT: Can we get away with adding "{0} is a/n {1}" here?
+            # REVISIT: Can we deprecate the "is a subtype of" reading?
+            @constellation.Reading(inheritance_fact, 1, :role_sequence => rs, :text => "{0} is a subtype of {1}")
+
+            rs2 = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs2, 0, :role => super_role)
+            @constellation.RoleRef(rs2, 1, :role => sub_role)
+            # Decide in which order to include is a/is an. Provide both, but in order.
+            n = 'aeiouh'.include?(sub_role.concept.name.downcase[0]) ? 1 : 0
+            @constellation.Reading(inheritance_fact, 2+n, :role_sequence => rs2, :text => "{0} is a {1}")
+            @constellation.Reading(inheritance_fact, 3-n, :role_sequence => rs2, :text => "{0} is an {1}")
+
+            if is_identifying_supertype
+              inheritance_fact.provides_identification = true
+            end
+
+            # Create uniqueness constraints over the subtyping fact type.
+            p1rs = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(p1rs, 0).role = sub_role
+            pc1 = @constellation.PresenceConstraint(:new, :vocabulary => @vocabulary)
+            pc1.name = "#{@entity_type.name}MustHaveSupertype#{supertype.name}"
+            pc1.role_sequence = p1rs
+            pc1.is_mandatory = true   # A subtype instance must have a supertype instance
+            pc1.min_frequency = 1
+            pc1.max_frequency = 1
+            pc1.is_preferred_identifier = false
+
+            p2rs = @constellation.RoleSequence(:new)
+            constellation.RoleRef(p2rs, 0).role = super_role
+            pc2 = constellation.PresenceConstraint(:new, :vocabulary => @vocabulary)
+            pc2.name = "#{supertype.name}MayBeA#{@entity_type.name}"
+            pc2.role_sequence = p2rs
+            pc2.is_mandatory = false
+            pc2.min_frequency = 0
+            pc2.max_frequency = 1
+            # The supertype role often identifies the subtype:
+            pc2.is_preferred_identifier = inheritance_fact.provides_identification
+          end
+        end
+
+        def make_entity_type_refmode_valuetypes(name, mode, parameters)
+          vt_name = "#{name}#{mode}"
+          vt = nil
+          debug :entity, "Preparing value type #{vt_name} for reference mode" do
+            # Find or Create an appropriate ValueType called '#{vt_name}', of the supertype '#{mode}'
+            unless vt = @constellation.Concept[[@vocabulary.identifying_role_values, vt_name]] or
+                   vt = @constellation.Concept[[@vocabulary.identifying_role_values, vt_name = "#{name} #{mode}"]]
+              base_vt = @constellation.ValueType(@vocabulary, mode)
+              vt = @constellation.ValueType(@vocabulary, vt_name, :supertype => base_vt)
+              if parameters
+                length, scale = *parameters
+                vt.length = length if length
+                vt.scale = scale if scale
+              end
+            else
+              debug :entity, "Value type #{vt_name} already exists"
+            end
+          end
+
+          # REVISIT: If we do this, it gets emitted twice when we generate CQL.
+          # The generator should detect that the value_constraint is the same and not emit it.
+          #if (ranges = identification[:value_constraint])
+          #  vt.value_constraint = value_constraint(ranges, identification[:enforcement])
+          #end
+          @reference_mode_value_type = vt
+        end
+
+        def complete_reference_mode_fact_type(fact_types)
+          return unless identifying_type = @reference_mode_value_type
+
+          # Find an existing fact type, if any:
+          entity_role = identifying_role = nil
+          fact_type = fact_types.detect do |ft|
+            identifying_role = ft.all_role.detect{|r| r.concept == identifying_type } and
+            entity_role = ft.all_role.detect{|r| r.concept == @entity_type }
+          end
+
+          # Create an identifying fact type if needed:
+          unless fact_type
+            fact_type = @constellation.FactType(:new)
+            fact_types << fact_type
+            entity_role = @constellation.Role(fact_type, 0, :concept => @entity_type)
+            identifying_role = @constellation.Role(fact_type, 1, :concept => identifying_type)
+          end
+          @identification[0].role = identifying_role
+
+          if (value_constraint = @identification[0].value_constraint)
+            # The value_constraint applies only to the value role, not to the underlying value type
+            # Decide whether this puts the value_constraint in the right place:
+            value_constraint.constellation = fact_type.constellation
+            identifying_role.role_value_constraint = value_constraint.compile
+          end
+
+          # Find all role sequences over the fact type's two roles
+          rss = entity_role.all_role_ref.select do |rr|
+            rr.role_sequence.all_role_ref.size == 2 &&
+              (rr.role_sequence.all_role_ref.to_a-[rr])[0].role == identifying_role
+          end.map{|rr| rr.role_sequence}
+
+          # Make a forward reading, if there is none already:
+          # Find or create RoleSequences for the forward and reverse readings:
+          rs01 = rss.select{|rs| rs.all_role_ref.sort_by{|rr| rr.ordinal}.map(&:role) == [entity_role, identifying_role] }[0]
+          if !rs01
+            rs01 = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs01, 0, :role => entity_role)
+            @constellation.RoleRef(rs01, 1, :role => identifying_role)
+          end
+          if rs01.all_reading.empty?
+            @constellation.Reading(fact_type, fact_type.all_reading.size, :role_sequence => rs01, :text => "{0} has {1}")
+            debug :mode, "Creating new forward reading '#{entity_role.concept.name} has #{identifying_type.name}'"
+          else
+            debug :mode, "Using existing forward reading"
+          end
+
+          # Make a reverse reading if none exists
+          rs10 = rss.select{|rs| rs.all_role_ref.sort_by{|rr| rr.ordinal}.map(&:role) == [identifying_role, entity_role] }[0]
+          if !rs10
+            rs10 = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs10, 0, :role => identifying_role)
+            @constellation.RoleRef(rs10, 1, :role => entity_role)
+          end
+          if rs10.all_reading.empty?
+            @constellation.Reading(fact_type, fact_type.all_reading.size, :role_sequence => rs10, :text => "{0} is of {1}")
+            debug :mode, "Creating new reverse reading '#{identifying_type.name} is of #{entity_role.concept.name}'"
+          else
+            debug :mode, "Using existing reverse reading"
+          end
+
+          # Entity must have one identifying instance. Find or create the role sequence, then create a PC if necessary
+          rs0 = entity_role.all_role_ref.select{|rr| rr.role_sequence.all_role_ref.size == 1}[0]
+          if rs0
+            rs0 = rs0.role_sequence
+            debug :mode, "Using existing EntityType role sequence"
+          else
+            rs0 = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs0, 0, :role => entity_role)
+            debug :mode, "Creating new EntityType role sequence"
+          end
+          if (rs0.all_presence_constraint.size == 0)
+            constraint = @constellation.PresenceConstraint(
+              :new,
+              :name => '',
+              :vocabulary => @vocabulary,
+              :role_sequence => rs0,
+              :min_frequency => 1,
+              :max_frequency => 1,
+              :is_preferred_identifier => false,
+              :is_mandatory => true
+            )
+            debug :mode, "Creating new EntityType PresenceConstraint"
+          else
+            debug :mode, "Using existing EntityType PresenceConstraint"
+          end
+
+          # Value Type must have a value type. Find or create the role sequence, then create a PC if necessary
+          debug :mode, "identifying_role has #{identifying_role.all_role_ref.size} attached sequences"
+          debug :mode, "identifying_role has #{identifying_role.all_role_ref.select{|rr| rr.role_sequence.all_role_ref.size == 1}.size} unary sequences"
+          rs1 = identifying_role.all_role_ref.select{|rr| rr.role_sequence.all_role_ref.size == 1 ? rr.role_sequence : nil }.compact[0]
+          if (!rs1)
+            rs1 = @constellation.RoleSequence(:new)
+            @constellation.RoleRef(rs1, 0, :role => identifying_role)
+            debug :mode, "Creating new ValueType role sequence"
+          else
+            rs1 = rs1.role_sequence
+            debug :mode, "Using existing ValueType role sequence"
+          end
+          if (rs1.all_presence_constraint.size == 0)
+            constraint = @constellation.PresenceConstraint(
+              :new,
+              :name => '',
+              :vocabulary => @vocabulary,
+              :role_sequence => rs1,
+              :min_frequency => 0,
+              :max_frequency => 1,
+              :is_preferred_identifier => true,
+              :is_mandatory => false
+            )
+            debug :mode, "Creating new ValueType PresenceConstraint"
+          else
+            debug :mode, "Marking existing ValueType PresenceConstraint as preferred"
+            rs1.all_presence_constraint[0].is_preferred_identifier = true
+          end
+        end
+
+      end
+
+    end
+  end
+end
+

data/lib/activefacts/cql/compiler/fact.rb

@@ -0,0 +1,300 @@
+module ActiveFacts
+  module CQL
+    class Compiler < ActiveFacts::CQL::Parser
+
+      class Fact < Definition
+        def initialize readings, population_name = ''
+          @readings = readings
+          @population_name = population_name
+        end
+
+        def compile
+          @population = @constellation.Population(@vocabulary, @population_name)
+
+          @context = CompilationContext.new(@vocabulary)
+          @readings.each{ |reading| reading.identify_players_with_role_name(@context) }
+          @readings.each{ |reading| reading.identify_other_players(@context) }
+          @readings.each{ |reading| reading.bind_roles @context }
+
+          # Figure out the simple existential facts and find fact types:
+          @bound_instances = {}  # Instances indexed by binding
+          @bound_fact_types = []
+          @bound_facts = []
+          @unbound_readings = @readings.
+            map do |reading|
+              bind_literal_or_fact_type reading
+            end.
+            compact
+
+          # Because the fact types may include forward references, we must
+          # process the list repeatedly until we make no further progress.
+          @pass = 0 # Repeat until we make no more progress:
+          true while bind_more_facts
+
+          # Any remaining unbound facts are a problem we can bitch about:
+          complain_incomplete unless @unbound_readings.empty?
+
+          @bound_facts.uniq # N.B. this includes Instance objects (existential facts)
+        end
+
+        def bind_literal_or_fact_type reading
+          # Every bound word (term) in the phrases must have a literal
+          # OR be bound to an entity type identified by the phrases
+
+          # Any clause that has one binding and no other word is
+          # either a value instance or a simply-identified entity.
+          reading.role_refs.map do |role_ref|
+            next role_ref unless l = role_ref.literal
+            player = role_ref.binding.player
+            # raise "A literal may not be an objectification" if role_ref.role_ref.objectification_join
+            # raise "Not processing facts involving objectification joins yet" if role_ref.role_ref
+            debug :instance, "Making #{player.class.basename} #{player.name} using #{l.inspect}" do
+              @bound_instances[role_ref.binding] =
+                instance_identified_by_literal player, l
+            end
+            role_ref
+          end
+
+          if reading.phrases.size == 1 && (role_ref = reading.phrases[0]).is_a?(Compiler::RoleRef)
+            # This is an existential fact (like "Name 'foo'", or "Company 'Microsoft'")
+            # @bound_instances[role_ref.binding]
+            nil # Nothing to see here, move along
+          else
+            @bound_fact_types << reading.match_existing_fact_type(@context)
+            reading
+          end
+        end
+
+        # Take one pass through the @unbound_readings, processing (and removing) any that have all pre-requisites
+        def bind_more_facts
+          @pass += 1
+
+          progress = false
+          debug :instance, "Pass #{@pass} with #{@unbound_readings.size} readings to consider" do
+            @unbound_readings.map! do |reading|
+              # See if we can create the fact instance for this reading yet
+
+              # Find the roles of this reading that do not yet have an entry in @bound_instances:
+              bare_roles = reading.role_refs.
+                select do |role_ref|
+                  !role_ref.literal && !@bound_instances[role_ref.binding]
+                end
+
+              debug :instance, "Considering '#{reading.fact_type.preferred_reading.expand}' with bare roles: #{bare_roles.map{|role_ref| role_ref.player.name}*", "} "
+
+              if bare_roles.size == 0
+                reading = nil if bind_complete_fact reading
+              elsif bare_roles.size == 1 &&
+                  (binding = bare_roles[0].binding) &&
+                  (et = binding.player).is_a?(ActiveFacts::Metamodel::EntityType) &&
+                  et.preferred_identifier.role_sequence.all_role_ref.detect{|rr| rr.role.fact_type == reading.fact_type}
+
+                reading = nil if bind_entity_if_identifier_ready reading, et, binding
+              end
+              progress = true unless reading
+              reading
+            end
+            @unbound_readings.compact!
+          end # debug
+          progress
+        end
+
+        def bind_complete_fact reading
+          debug :instance, "All bindings in '#{reading.fact_type.preferred_reading.expand}' contain instances; create the fact type"
+          instances = reading.role_refs.map{|rr| @bound_instances[rr.binding]}
+          debug :instance, "Instances are #{instances.map{|i| "#{i.concept.name} #{i.value.inspect}"}*", "}"
+
+          # Check that this fact doesn't already exist
+          fact = reading.fact_type.all_fact.detect{|f|
+            # Get the role values of this fact in the order of the reading we just bound
+            role_values_in_reading_order = f.all_role_value.sort_by do |rv|
+              reading.reading.role_sequence.all_role_ref.detect{|rr| rr.role == rv.role}.ordinal
+            end
+            # If all this fact's role values are played by the bound instances, it's the same fact
+            !role_values_in_reading_order.zip(instances).detect{|rv, i| rv.instance != i }
+          }
+          unless fact
+            fact = @constellation.Fact(:new, :fact_type => reading.fact_type, :population => @population)
+            @bound_facts << fact
+            instance =
+              @constellation.Instance(:new, :concept => reading.fact_type.entity_type, :fact => fact, :population => @population)
+            @bound_facts << instance
+            reading.reading.role_sequence.all_role_ref.zip(instances).each do |rr, instance|
+              debug :instance, "New fact has #{instance.concept.name} role #{instance.value.inspect}"
+              # REVISIT: Any residual adjectives after the fact type matching are lost here.
+              @constellation.RoleValue(:fact => fact, :instance => instance, :role => rr.role, :population => @population)
+            end
+          else
+            debug :instance, "Found existing fact type instance"
+          end
+          true
+        end
+
+        # If we have one bare role (no literal or instance) played by an entity type,
+        # and the bound fact type participates in the identifier, we might now be able
+        # to create the entity instance.
+        def bind_entity_if_identifier_ready reading, entity_type, binding
+          # Check this instance doesn't already exist already:
+          identifying_binding = (reading.role_refs.map{|rr| rr.binding}-[binding])[0]
+          identifying_instance = @bound_instances[identifying_binding]
+          preferred_identifier = entity_type.preferred_identifier
+
+          debug :instance, "This clause associates a new #{binding.player.name} with a #{identifying_binding.player.name}#{identifying_instance ? " which exists" : ""}"
+
+          identifying_role_ref = preferred_identifier.role_sequence.all_role_ref.detect { |rr|
+              rr.role.fact_type == reading.fact_type && rr.role.concept == identifying_binding.player
+            }
+          unless identifying_role_ref
+            # This shold never happen; we already bound all role_refs
+            debug :instance, "Failed to find a #{identifying_instance.concept.name}"
+            return false # We can't do this yet
+          end
+          role_value = identifying_instance.all_role_value.detect do |rv|
+            rv.fact.fact_type == identifying_role_ref.role.fact_type
+          end
+          if role_value
+            instance = (role_value.fact.all_role_value.to_a-[role_value])[0].instance
+            debug :instance, "Found an existing instance (of #{instance.concept.name}) from a previous definition"
+            @bound_instances[binding] = instance
+            return true  # Done with this reading
+          end
+
+          pi_role_refs = preferred_identifier.role_sequence.all_role_ref
+          # For each pi role, we have to find the fact clause, which contains the binding we need.
+          # Then we have to create an instance of each fact
+          identifiers =
+            pi_role_refs.map do |rr|
+              fact_a = @readings.detect{|reading| rr.role.fact_type == reading.fact_type}
+              identifying_role_ref = fact_a.role_refs.select{|role_ref| role_ref.binding != binding}[0]
+              identifying_binding = identifying_role_ref ? identifying_role_ref.binding : nil
+              identifying_instance = @bound_instances[identifying_binding]
+
+              [rr, fact_a, identifying_binding, identifying_instance]
+            end
+          if identifiers.detect{ |i| !i[3] }  # Not all required facts are bound yet
+            debug :instance, "Can't go through with creating #{binding.player.name}; not all the identifying facts are in"
+            return false
+          end
+
+          debug :instance, "Going ahead with creating #{binding.player.name} using #{identifiers.size} roles"
+          instance = @constellation.Instance(:new, :concept => entity_type, :population => @population)
+          @bound_instances[binding] = instance
+          @bound_facts << instance
+          identifiers.each do |rr, fact_a, identifying_binding, identifying_instance|
+            # This reading provides the identifying literal for the entity_type
+            id_fact = @constellation.Fact(:new, :fact_type => rr.role.fact_type, :population => @population)
+            @bound_facts << id_fact
+            role = (rr.role.fact_type.all_role.to_a-[rr.role])[0]
+            @constellation.RoleValue(:instance => instance, :fact => id_fact, :population => @population, :role => role)
+            @constellation.RoleValue(:instance => identifying_instance, :fact => id_fact, :role => rr.role, :population => @population)
+          end
+
+          true  # Done with this reading
+        end
+
+        def instance_identified_by_literal concept, literal
+          if concept.is_a?(ActiveFacts::Metamodel::EntityType)
+            entity_identified_by_literal concept, literal
+          else
+            debug :instance, "Making ValueType #{concept.name} #{literal.inspect} #{@population.name.size>0 ? " in "+@population.name.inspect : ''}" do
+
+              is_a_string = String === literal
+              instance = @constellation.Instance.detect do |key, i|
+                  # REVISIT: And same unit
+                  i.population == @population &&
+                    i.value &&
+                    i.value.literal == literal &&
+                    i.value.is_a_string == is_a_string
+                end
+              #instance = concept.all_instance.detect { |instance|
+              #  instance.population == @population && instance.value == literal
+              #}
+              debug :instance, "This #{concept.name} value already exists" if instance
+              unless instance
+                instance = @constellation.Instance(
+                    :new,
+                    :concept => concept,
+                    :population => @population,
+                    :value => [literal.to_s, is_a_string, nil]
+                  )
+                @bound_facts << instance
+              end
+              instance
+            end
+          end
+        end
+
+        def entity_identified_by_literal concept, literal
+          # A literal that identifies an entity type means the entity type has only one identifying role
+          # That role is played either by a value type, or by another similarly single-identified entity type
+          debug "Making EntityType #{concept.name} identified by '#{literal}' #{@population.name.size>0 ? " in "+@population.name.inspect : ''}" do
+            identifying_role_refs = concept.preferred_identifier.role_sequence.all_role_ref
+            raise "Single literal cannot satisfy multiple identifying roles for #{concept.name}" if identifying_role_refs.size > 1
+            role = identifying_role_refs.single.role
+            identifying_instance = instance_identified_by_literal role.concept, literal
+            existing_instance = nil
+            instance_rv = identifying_instance.all_role_value.detect { |rv|
+              next false unless rv.population == @population         # Not this population
+              next false unless rv.fact.fact_type == role.fact_type # Not this fact type
+              other_role_value = (rv.fact.all_role_value-[rv])[0]
+              existing_instance = other_role_value.instance
+              other_role_value.instance.concept == concept          # Is it this concept?
+            }
+            if instance_rv
+              instance = existing_instance
+              debug :instance, "This #{concept.name} entity already exists"
+            else
+              fact = @constellation.Fact(:new, :fact_type => role.fact_type, :population => @population)
+              @bound_facts << fact
+              instance = @constellation.Instance(:new, :concept => concept, :population => @population)
+              @bound_facts << instance
+              # The identifying fact type has two roles; create both role instances:
+              @constellation.RoleValue(:instance => identifying_instance, :fact => fact, :population => @population, :role => role)
+              @constellation.RoleValue(:instance => instance, :fact => fact, :population => @population, :role => (role.fact_type.all_role-[role])[0])
+            end
+            instance
+          end
+        end
+
+        def complain_incomplete
+          if @unbound_readings.size > 0
+            # Provide a readable description of the problem here, by showing each binding with no instance
+            missing_bindings = @unbound_readings.
+              map do |reading|
+                reading.role_refs.
+                  select do |rr|
+                    !@bound_instances[rr.binding]
+                  end.
+                  map do |role_ref|
+                    role_ref.binding
+                  end
+              end.
+              flatten.
+              uniq
+
+            raise "Not enough facts are given to identify #{
+                missing_bindings.
+                  sort_by{|b| b.key}.
+                  map do |b|
+                    player_identifier =
+                      if b.player.is_a?(ActiveFacts::Metamodel::EntityType)
+                        "lacking " +
+                          b.player.preferred_identifier.role_sequence.all_role_ref.map do |rr|
+                            [ rr.leading_adjective, rr.role.role_name || rr.role.concept.name, rr.trailing_adjective ].compact*" "
+                          end*", "
+                      else
+                        "needs a value"
+                      end
+                    [
+                      b.refs[0].leading_adjective, b.player.name, b.refs[0].trailing_adjective
+                    ].compact*" " +
+                      " (#{player_identifier})"
+                  end*" or "
+              }"
+          end
+        end
+
+      end
+    end
+  end
+end