activefacts 0.8.8 → 0.8.9

data/lib/activefacts/version.rb

@@ -5,5 +5,5 @@
 # Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 module ActiveFacts
-  VERSION = '0.8.8'
+  VERSION = '0.8.9'
 end

data/lib/activefacts/vocabulary/extensions.rb

@@ -89,7 +89,11 @@ module ActiveFacts
 
     class RoleRef
       def describe
-        role_name + (join_node ? " JN#{join_node.ordinal}" : '')
+        role_name
+      end
+
+      def preferred_role_ref
+        role.fact_type.preferred_reading.role_sequence.all_role_ref.detect{|rr| rr.role == role}
       end
 
       def role_name(joiner = "-")
@@ -486,104 +490,128 @@ module ActiveFacts
       def describe(role = nil)
         "#{subtype.name} is a kind of #{supertype.name}"
       end
+
+      def supertype_role
+        (roles = all_role.to_a)[0].concept == supertype ? roles[0] : roles[1]
+      end
+
+      def subtype_role
+        (roles = all_role.to_a)[0].concept == subtype ? roles[0] : roles[1]
+      end
     end
 
     class JoinStep
       def describe
-        input_role_ref = input_join_node.all_role_ref.detect{|rr| rr.role.fact_type == fact_type}
-        output_role_ref = output_join_node.all_role_ref.detect{|rr| rr.role.fact_type == fact_type}
-        "from node #{input_join_node.ordinal} #{input_role_ref ? input_role_ref.role.concept.name : input_join_node.concept.name}"+
-        " to node #{output_join_node.ordinal} #{output_role_ref ? output_role_ref.role.concept.name : output_join_node.concept.name}"+
-        ": #{is_anti && 'not '}#{is_outer && 'maybe '}#{fact_type.default_reading}"
+        "JoinStep " +
+          "#{is_outer && 'maybe '}" +
+          (is_unary_step ? " (unary) " : "from #{input_join_role.describe} ") +
+          "#{is_anti && 'not '}" +
+          "to #{output_join_role.describe} " +
+          "over " + (is_objectification_step ? 'objectification ' : '') +
+          "'#{fact_type.default_reading}'"
       end
 
       def is_unary_step
         # Preserve this in case we have to use a real join_node for the phantom
-        # input_join_node.all_role_ref.detect{|rr| rr.role.fact_type.is_a?(ImplicitFactType) && rr.role.fact_type.role.fact_type.all_role.size == 1 }
-        input_join_node == output_join_node
+        input_join_role == output_join_role
       end
 
       def is_objectification_step
         fact_type.is_a?(ImplicitFactType)
       end
+
+      def all_join_role
+        [input_join_role, output_join_role].uniq + all_incidental_join_role.to_a
+      end
+
+      def external_fact_type
+        fact_type.is_a?(ImplicitFactType) ? fact_type.role.fact_type : fact_type
+      end
     end
 
     class JoinNode
       def describe
-        concept.name
+        concept.name +
+          (subscript ? "(#{subscript})" : '') +
+          " JN#{ordinal}" +
+#          (all_join_role.detect{|jr| jr.role_ref} ? " (projected)" : "") +
+          (value ? ' = '+value.describe : '')
+      end
+
+      def all_join_step
+        all_join_role.map do |jr|
+          jr.all_join_step_as_input_join_role.to_a +
+            jr.all_join_step_as_output_join_role.to_a
+        end.
+          flatten.
+          uniq
+      end
+    end
+
+    class JoinRole
+      def describe
+        "#{role.concept.name} JN#{join_node.ordinal}" +
+          (role_ref ? " (projected)" : "")
+      end
+
+      def all_join_step
+        (all_join_step_as_input_join_role.to_a +
+          all_join_step_as_output_join_role.to_a +
+          [join_step]).flatten.compact.uniq
       end
     end
 
     class Join
       def show
+        steps_shown = {}
         debug :join, "Displaying full contents of Join #{join_id}" do
           all_join_node.sort_by{|jn| jn.ordinal}.each do |join_node|
-            debug :join, "Node #{join_node.ordinal} for #{join_node.concept.name}" do
-              (join_node.all_join_step_as_input_join_node.to_a +
-                join_node.all_join_step_as_output_join_node.to_a).
-                uniq.
+            debug :join, "#{join_node.describe}" do
+              join_node.all_join_step.
                 each do |join_step|
-                  debug :join, "#{
-                      join_step.is_unary_step ? 'unary ' : ''
-                    }#{
-                      join_step.is_objectification_step ? 'objectification ' : ''
-                    }step #{join_step.describe}"
+                  next if steps_shown[join_step]
+                  steps_shown[join_step] = true
+                  debug :join, "#{join_step.describe}"
                 end
-              join_node.all_role_ref.each do |role_ref|
-                debug :join, "reference #{role_ref.describe} in '#{role_ref.role.fact_type.default_reading}' over #{role_ref.role_sequence.describe}#{role_ref.role_sequence == role_sequence ? ' (projected)' : ''}"
+              join_node.all_join_role.each do |join_role|
+                debug :join, "role of #{join_role.describe} in '#{join_role.role.fact_type.default_reading}'"
               end
             end
           end
         end
       end
 
+      def all_join_step
+        all_join_node.map{|jn| jn.all_join_step.to_a}.flatten.uniq
+      end
+
+      # Check all parts of this join for validity
       def validate
         show
         return
 
-        # Check all parts of this join for validity
-        jns = all_join_node.sort_by{|jn| jn.ordinal}
-        jns.each_with_index do |jn, i|
-          raise "Join node #{i} should have ordinal #{jn.ordinal}" unless jn.ordinal == i
-        end
-
         # Check the join nodes:
-        steps = []
-        jns.each_with_index do |join_node, i|
+        join_steps = []
+        join_nodes = all_join_node.sort_by{|jn| jn.ordinal}
+        join_nodes.each_with_index do |join_node, i|
+          raise "Join node #{i} should have ordinal #{join_node.ordinal}" unless join_node.ordinal == i
           raise "Join Node #{i} has missing concept" unless join_node.concept
-          if join_node.all_role_ref.detect{|rr| rr.role.concept != join_node.concept }
-            raise "All role references for join node #{join_node.ordinal} should be for #{
-                join_node.concept.name
-              } but we have #{
-                (join_node.all_role_ref.map{|rr| rr.role.concept.name}-[join_node.concept.name]).uniq*', '
-              }"
+          join_node.all_join_role do |join_role|
+            raise "Join Node for #{concept.name} includes role played by #{join_role.concept.name}" unless join_role.concept == concept
           end
-          steps += join_node.all_join_step_as_input_join_node.to_a
-          steps += join_node.all_join_step_as_output_join_node.to_a
-
-          # REVISIT: All Role References must be in a role sequence that covers one fact type exactly (why?)
-          # REVISIT: All such role references must have a join node in this join. (why?)
+          join_steps += join_node.all_join_step
         end
+        join_steps.uniq!
 
         # Check the join steps:
-        steps.uniq!
-        steps.each_with_index do |join_step, i|
-          raise "Join Step #{i} has missing fact type" unless join_step.fact_type
-          raise "Join Step #{i} has missing input node" unless join_step.input_join_node
-          raise "Join Step #{i} has missing output node" unless join_step.output_join_node
-          debugger
-          p join_step.fact_type.default_reading
-          p join_step.input_join_node.all_role_ref.map(&:describe)
-          p join_step.output_join_node.all_role_ref.map(&:describe)
-=begin
-          unless join_step.input_join_node.all_role_ref.
-              detect do |rr|
-                rr.role.fact_type == join_step.fact_type
-                or rr.role.fact_type.is_a?(ImplicitFactType) && rr.role.fact_type.role.fact_type == rr.join_step.concept
-              end
-            raise "Join Step #{join_step.describe} has nodes not matching its fact type"
+        join_steps.each do |join_step|
+          raise "Join Step has missing fact type" unless join_step.fact_type
+          raise "Join Step has missing input node" unless join_step.input_join_role
+          raise "Join Step has missing output node" unless join_step.output_join_role
+          if (role = input_join_role).role.fact_type != fact_type or
+            (role = output_join_role).role.fact_type != fact_type
+            raise "Join Step has role #{role.describe} which doesn't belong to the fact type '#{fact_type.default_reading}' it traverses"
           end
-=end
         end
 
         # REVISIT: Do a connectivity check
@@ -619,6 +647,7 @@ module ActiveFacts
               @role_sequence = role_sequence
             end
             def join_node; nil; end
+            def join_role; nil; end
             def leading_adjective; nil; end
             def trailing_adjective; nil; end
             def describe
@@ -705,7 +734,7 @@ module ActiveFacts
             objectification_role = role.implicit_fact_type.all_role.single # Find the phantom role here
           else
             objectification_role_supertypes = counterpart_role_supertypes
-            objectification_role = nil
+            objectification_role = counterpart_role
           end
 
           if !d_c_o
@@ -733,7 +762,7 @@ module ActiveFacts
       end
 
       # Choose the first entry in the first non-empty supertypes list:
-      if options != :counterpart
+      if options != :counterpart && proximate_sups[0]
         [ proximate_sups[0], roles ]
       elsif !counterpart_sups.empty?
         [ counterpart_sups[0], counterpart_roles ]
@@ -742,5 +771,67 @@ module ActiveFacts
       end
     end
 
+    class Fact
+      def verbalise(context = nil)
+        reading = fact_type.preferred_reading
+        reading_roles = reading.role_sequence.all_role_ref.sort_by{|rr| rr.ordinal}.map{|rr| rr.role }
+        role_values_in_reading_order = all_role_value.sort_by{|rv| reading_roles.index(rv.role) }
+        instance_verbalisations = role_values_in_reading_order.map do |rv|
+          if rv.instance.value
+            v = rv.instance.verbalise
+          else
+            if (c = rv.instance.concept).is_a?(EntityType)
+              if !c.preferred_identifier.role_sequence.all_role_ref.detect{|rr| rr.role.fact_type == fact_type}
+                v = rv.instance.verbalise
+              end
+            end
+          end
+          next nil unless v
+          v.to_s.sub(/(#{rv.instance.concept.name}|\S*)\s/,'')
+        end
+        reading.expand([], false, instance_verbalisations)
+      end
+    end
+
+    class Instance
+      def verbalise(context = nil)
+        return "#{concept.name} #{value}" if concept.is_a?(ValueType)
+
+        return "#{concept.name} where #{fact.verbalise(context)}" if concept.fact_type
+
+        # It's an entity that's not an objectified fact type
+        # REVISIT: If it has a simple identifier, there's no need to fully verbalise the identifying facts
+        pi = concept.preferred_identifier
+        identifying_role_refs = pi.role_sequence.all_role_ref_in_order
+        "#{concept.name}" +
+          " is identified by " +      # REVISIT: Where the single fact type is TypeInheritance, we can shrink this
+          if identifying_role_refs.size == 1 &&
+            (role = identifying_role_refs[0].role) &&
+            (my_role = (role.fact_type.all_role.to_a-[role])[0]) &&
+            (identifying_fact = my_role.all_role_value.detect{|rv| rv.instance == self}.fact) &&
+            (identifying_instance = identifying_fact.all_role_value.detect{|rv| rv.role == role}.instance)
+
+              "its #{identifying_instance.verbalise(context)}"
+          else
+            identifying_role_refs.map do |rr|
+              rr = rr.preferred_role_ref
+              [ (l = rr.leading_adjective) ? l+"-" : nil,
+                rr.role.role_name || rr.role.concept.name,
+                (t = rr.trailing_adjective) ? l+"-" : nil
+              ].compact*""
+            end * " and " +
+            " where " +
+            identifying_role_refs.map do |rr|  # Go through the identifying roles and emit the facts that define them
+              instance_role = concept.all_role.detect{|r| r.fact_type == rr.role.fact_type}
+              identifying_fact = all_role_value.detect{|rv| rv.fact.fact_type == rr.role.fact_type}.fact
+              #counterpart_role = (rr.role.fact_type.all_role.to_a-[instance_role])[0]
+              #identifying_instance = counterpart_role.all_role_value.detect{|rv| rv.fact == identifying_fact}.instance
+              identifying_fact.verbalise(context)
+            end*", "
+          end
+
+      end
+    end
+
   end
 end

data/lib/activefacts/vocabulary/metamodel.rb

@@ -128,6 +128,10 @@ module ActiveFacts
       value_type 
     end
 
+    class Subscript < UnsignedInteger
+      value_type :length => 16
+    end
+
     class Text < String
       value_type :length => 256
     end
@@ -207,7 +211,6 @@ module ActiveFacts
     class Join
       identified_by :join_id
       one_to_one :join_id, :mandatory => true     # See JoinId.join
-      has_one :role_sequence, :mandatory => true  # See RoleSequence.all_join
     end
 
     class JoinNode
@@ -215,15 +218,8 @@ module ActiveFacts
       has_one :concept, :mandatory => true        # See Concept.all_join_node
       has_one :join, :mandatory => true           # See Join.all_join_node
       has_one :ordinal, :mandatory => true        # See Ordinal.all_join_node
-    end
-
-    class JoinStep
-      identified_by :input_join_node, :output_join_node
-      has_one :fact_type, :mandatory => true      # See FactType.all_join_step
-      has_one :input_join_node, :class => JoinNode, :mandatory => true  # See JoinNode.all_join_step_as_input_join_node
-      maybe :is_anti
-      maybe :is_outer
-      has_one :output_join_node, :class => JoinNode, :mandatory => true  # See JoinNode.all_join_step_as_output_join_node
+      has_one :subscript                          # See Subscript.all_join_node
+      has_one :value                              # See Value.all_join_node
     end
 
     class Position
@@ -381,6 +377,22 @@ module ActiveFacts
       has_one :rotation_setting                   # See RotationSetting.all_fact_type_shape
     end
 
+    class JoinRole
+      identified_by :join_node, :role
+      has_one :join_node, :mandatory => true      # See JoinNode.all_join_role
+      has_one :role, :mandatory => true           # See Role.all_join_role
+      has_one :join_step, :counterpart => :incidental_join_role  # See JoinStep.all_incidental_join_role
+    end
+
+    class JoinStep
+      identified_by :input_join_role, :output_join_role
+      has_one :fact_type, :mandatory => true      # See FactType.all_join_step
+      has_one :input_join_role, :class => JoinRole, :mandatory => true  # See JoinRole.all_join_step_as_input_join_role
+      maybe :is_anti
+      maybe :is_outer
+      has_one :output_join_role, :class => JoinRole, :mandatory => true  # See JoinRole.all_join_step_as_output_join_role
+    end
+
     class ModelNoteShape < Shape
       has_one :context_note, :mandatory => true   # See ContextNote.all_model_note_shape
     end
@@ -427,7 +439,7 @@ module ActiveFacts
       has_one :ordinal, :mandatory => true        # See Ordinal.all_role_ref
       has_one :role, :mandatory => true           # See Role.all_role_ref
       has_one :role_sequence, :mandatory => true  # See RoleSequence.all_role_ref
-      has_one :join_node                          # See JoinNode.all_role_ref
+      one_to_one :join_role                       # See JoinRole.role_ref
       has_one :leading_adjective, :class => Adjective  # See Adjective.all_role_ref_as_leading_adjective
       has_one :trailing_adjective, :class => Adjective  # See Adjective.all_role_ref_as_trailing_adjective
     end

data/lib/activefacts/vocabulary/verbaliser.rb

@@ -15,10 +15,48 @@ module ActiveFacts
     # There may be more than one Player for the same Concept. If adjectives or role
     # names don't make such duplicates unambiguous, subscripts will be generated.
     # Thus, the verbalisation context must be completely populated before subscript
-    # generation, which must be before any verbalisation occurs.
+    # generation, which must be before any Player name gets verbalised.
     #
     # When a Player occurs in a Join, it corresponds to one Join Node of that Join.
-    # Each Player has one or more RoleRefs, which refer to Roles of that Concept.
+    # Each such Player has one or more JoinRoles, which refer to roles played by
+    # that Concept. Where a join traverses two roles of a ternary fact type, there
+    # will be a residual node that has only a single JoinRole with no other meaning.
+    # A JoinRole must be for exactly one Player, so is used to identify a Player.
+    #
+    # When a Player occurs outside a Join, it's identified by a projected RoleRef.
+    # REVISIT: This is untrue when a uniqueness constraint is imported from NORMA.
+    # In this case no join will be constructed to project the roles of the constrained
+    # object type (only the constrained roles will be projected) - this will be fixed.
+    #
+    # Each constraint (except Ring Constraints) has one or more RoleSequence containing
+    # the projected RoleRefs. Each constrained RoleSequence may have an associated Join.
+    # If it has a Join, each RoleRef is projected from a JoinRole, otherwise none are.
+    #
+    # The only type of join possible in a Ring Constraint is a subtyping join, which
+    # is always implicit and unambiguous, so is never instantiated.
+    #
+    # A constrained RoleSequence that has no explicit Join may have an implicit join,
+    # as per ORM2, when the roles aren't in the same fact type.  These implicit joins
+    # are over only one Concept, by traversing a single FactType (and possibly,
+    # multiple TypeInheritance FactTypes) for each RoleRef. Note however that when
+    # the Concept is an objectified Fact Type, the FactType traversed might be a
+    # phantom of the objectification. In the case of implicit joins, each Player is
+    # identified by the projected RoleRef, except for the joined-over Concept whose
+    # Player is... well, read the next paragraph!
+    #
+    # REVISIT: I believe that the foregoing paragraph is out of date, except with
+    # respect to PresenceConstraints imported from NORMA (both external mandatory
+    # and external uniqueness constraints). The joined-over Player in a UC is
+    # identified by its RoleRefs in the RoleSequence of the Fact Type's preferred
+    # reading. Subtyping joins in a mandatory constraint will probably malfunction.
+    # However, all other such joins are expliciti, and these should be also.
+    #
+    # For a SetComparisonConstraint, there are two or more constrained RoleSequences.
+    # The matching RoleRefs (by Ordinal position) are for joined players, that is,
+    # one individual instance plays both roles. The RoleRefs must (now) be for the
+    # same Concept (no implicit subtyping Join is allowed). Instead, the input modules
+    # find the closest common supertype and create explicit JoinSteps so its roles
+    # can be projected.
     #
     # When expanding Reading text however, the RoleRefs in the reading's RoleSequence
     # may be expected not to be attached to the Players for that reading. Instead,
@@ -29,8 +67,9 @@ module ActiveFacts
     class Verbaliser
       # Verbalisation context:
       attr_reader :players
-      attr_reader :player_by_role_ref
-      attr_reader :player_by_join_node
+      attr_reader :player_by_join_role        # Used for each join
+      attr_reader :player_joined_over         # Used when there's an implicit join
+      attr_reader :player_by_role_ref         # Used when a constrained role sequence has no join
 
       # The projected role references over which we're verbalising
       attr_reader :role_refs
@@ -46,8 +85,9 @@ module ActiveFacts
 
         # Verbalisation context:
         @players = []
+        @player_by_join_role = {}
         @player_by_role_ref = {}
-        @player_by_join_node = {}
+        @player_joined_over = nil
 
         # Join Verbaliser context:
         @join = nil
@@ -59,11 +99,12 @@ module ActiveFacts
       end
 
       class Player
-        attr_accessor :concept, :join_nodes_by_join, :subscript, :role_refs
+        attr_accessor :concept, :join_nodes_by_join, :subscript, :join_roles, :role_refs
         def initialize concept
           @concept = concept
           @join_nodes_by_join = {}
           @subscript = nil
+          @join_roles = []
           @role_refs = []
         end
 
@@ -71,32 +112,49 @@ module ActiveFacts
         # If more than one set of adjectives was used, this player must have been subject to loose binding.
         # This method is used to decide when subscripts aren't needed.
         def role_adjuncts
-          adjuncts = @role_refs.map{|rr| [rr.leading_adjective, rr.role.role_name, rr.trailing_adjective].compact}.uniq.sort
+          adjuncts = @role_refs.map{|rr|
+            [
+              rr.leading_adjective,
+              # rr.role.role_name,
+              rr.trailing_adjective
+            ].compact}.uniq.sort
           adjuncts.flatten*"_"
         end
+
+        def describe
+          @concept.name + (@join_nodes_by_join.size > 0 ? " (in #{@join_nodes_by_join.size} joins)" : "")
+        end
       end
 
       # Find or create a Player to which we can add this role_ref
-      def player(role_ref)
-        # REVISIT: This doesn't work when there are two joins over the underlying role, say each side of a Subset Constraint (see for example Supervision):
-        jn = (rrj = role_ref.role.all_role_ref.detect{|rr| rr.join_node}) && rrj.join_node
-        @player_by_role_ref[role_ref] or
-          @player_by_join_node[jn] or
-          @players.push(p = Player.new(role_ref.role.concept)) && p
+      def player(ref)
+        if ref.is_a?(ActiveFacts::Metamodel::JoinRole)
+          @player_by_join_role[ref] or
+            @players.push(p = Player.new(ref.role.concept)) && p
+        else
+          @player_by_role_ref[ref] or
+            ref.join_role && @player_by_join_role[ref.join_role] or
+            @players.push(p = Player.new(ref.role.concept)) && p
+        end
+      end
+
+      def add_join_role player, join_role
+        return if player.join_roles.include?(join_role)
+        jn = join_role.join_node
+        if jn1 = player.join_nodes_by_join[jn.join] and jn1 != jn
+          raise "Player for #{player.concept.name} may only have one join node per join, not #{jn1.concept.name} and #{jn.concept.name}"
+        end
+        player.join_nodes_by_join[jn.join] = jn
+        @player_by_join_role[join_role] = player
+        player.join_roles << join_role
       end
 
       # Add a RoleRef to an existing Player
       def add_role_player player, role_ref
         #debug :subscript, "Adding role_ref #{role_ref.object_id} to player #{player.object_id}"
-        if jn = role_ref.join_node
-          if jn1 = player.join_nodes_by_join[jn.join] and jn1 != jn
-            raise "Player for #{player.concept.name} may only have one join node per join, not #{jn1.concept.name} and #{jn.concept.name}"
-          end
-          player.join_nodes_by_join[jn.join] = jn
-          @player_by_join_node[jn] = player
-        end
-
-        if !player.role_refs.include?(role_ref)
+        if jr = role_ref.join_role
+          add_join_role(player, jr)
+        elsif !player.role_refs.include?(role_ref)
           debug :subscript, "Adding reference to player #{player.object_id} for #{role_ref.role.concept.name} in #{role_ref.role_sequence.describe} with #{role_ref.role_sequence.all_reading.size} readings"
           player.role_refs.push(role_ref)
           @player_by_role_ref[role_ref] = player
@@ -147,19 +205,47 @@ module ActiveFacts
         end
       end
 
+      def join_roles_have_same_player join_roles
+        return if join_roles.empty?
+
+        # If any of these join_roles are for a known player, use that, else make a new player.
+        existing_players = join_roles.map{|jr| @player_by_join_role[jr] }.compact.uniq
+        if existing_players.size > 1
+          raise "Can't join these roles to more than one existing player: #{existing_players.map{|p|p.concept.name}*', '}!"
+        end
+        p = existing_players[0] || player(join_roles[0])
+        debugger if join_roles.detect{|jr| jr.role.concept != p.concept }
+        debug :subscript, "Joining roles to #{p.describe}" do
+          join_roles.each do |jr|
+            debug :subscript, "#{jr.describe}" do
+              add_join_role p, jr
+            end
+          end
+        end
+      end
+
       # These RoleRefs are all for the same player. Find whether any of them has a player already
       def role_refs_have_same_player role_refs
         role_refs = role_refs.is_a?(Array) ? role_refs : role_refs.all_role_ref.to_a
         return if role_refs.empty?
+
         # If any of these role_refs are for a known player, use that, else make a new player.
         existing_players =
-          role_refs.map{|rr| @player_by_role_ref[rr] || @player_by_join_node[rr.join_node] }.compact.uniq
+          role_refs.map{|rr| @player_by_role_ref[rr] || @player_by_join_role[rr.join_role] }.compact.uniq
         if existing_players.size > 1
           raise "Can't join these role_refs to more than one existing player: #{existing_players.map{|p|p.concept.name}*', '}!"
         end
         p = existing_players[0] || player(role_refs[0])
+
         debug :subscript, "#{existing_players[0] ? 'Adding to existing' : 'Creating new'} player for #{role_refs.map{|rr| rr.role.concept.name}.uniq*', '}" do
           role_refs.each do |rr|
+            unless p.concept == rr.role.concept
+              # This happens in SubtypePI because uniqueness constraint is built without its implicit subtyping join.
+              # For now, explode only if there's no common supertype:
+              if 0 == (p.concept.supertypes_transitive & rr.role.concept.supertypes_transitive).size
+                raise "REVISIT: Internal error, trying to add role of #{rr.role.concept.name} to player #{p.concept.name}"
+              end
+            end
             add_role_player(p, rr)
           end
         end
@@ -167,9 +253,11 @@ module ActiveFacts
 
       def create_subscripts
         # Create subscripts, where necessary
+        @players.each { |p| p.subscript = nil } # Wipe subscripts
         @players.
           map{|p| [p, p.concept] }.
           each do |player, concept|
+            next if player.subscript  # Done previously
             dups = @players.select{|p| p.concept == concept && p.role_adjuncts == player.role_adjuncts }
             if dups.size == 1
               debug :subscript, "No subscript needed for #{concept.name}"
@@ -188,7 +276,7 @@ module ActiveFacts
       # and also define adjectives by using the hyphenated form (on at least the first occurrence).
       def expand_reading(reading, frequency_constraints = [], define_role_names = nil, value_constraints = [], &subscript_block)
         reading.expand(frequency_constraints, define_role_names, value_constraints) do |role_ref|
-          (p = player(role_ref) and p.subscript) ? "(#{p.subscript})" : ""
+          (!(role_ref.role.role_name and define_role_names) and p = player(role_ref) and p.subscript) ? "(#{p.subscript})" : ""
         end
       end
 
@@ -197,7 +285,6 @@ module ActiveFacts
       def role_refs_are_subtype_joined roles
         role_refs = roles.is_a?(Array) ? roles : roles.all_role_ref.to_a
         role_refs_by_concept = role_refs.inject({}) { |h, r| (h[r.role.concept] ||= []) << r; h }
-        # debugger if role_refs_by_concept.size > 1
         role_refs_by_concept.values.each { |rrs|  role_refs_have_same_player(rrs) }
       end
 
@@ -212,11 +299,11 @@ module ActiveFacts
         role_refs_have_same_player(role_refs)
       end
 
-      def prepare_role_sequence role_sequence
+      def prepare_role_sequence role_sequence, join_over = nil
         @role_refs = role_sequence.is_a?(Array) ? role_sequence : role_sequence.all_role_ref.to_a
 
-        if jrr = @role_refs.detect{|rr| rr.join_node}
-          return prepare_join_players(jrr.join_node.join)
+        if jrr = @role_refs.detect{|rr| rr.join_role && rr.join_role.join_node}
+          return prepare_join_players(jrr.join_role.join_node.join)
         end
 
         # Ensure that all the joined-over role_refs are indexed for subscript generation.
@@ -229,7 +316,7 @@ module ActiveFacts
           prrs = fact_type.preferred_reading.role_sequence.all_role_ref
           residual_roles = fact_type.all_role.select{|r| !@role_refs.detect{|rr| rr.role == r} }
           residual_roles.each do |role|
-            debug :subscript, "Adding residual role for #{role.concept.name} not covered in role sequence"
+            debug :subscript, "Adding residual role for #{role.concept.name} (in #{fact_type.default_reading}) not covered in role sequence"
             preferred_role_ref = prrs.detect{|rr| rr.role == role}
             if p = @player_by_role_ref[preferred_role_ref] and !p.role_refs.include?(preferred_role_ref)
               raise "Adding DUPLICATE residual role for #{role.concept.name}"
@@ -240,47 +327,66 @@ module ActiveFacts
       end
 
       def prepare_join_players join
-        debug :subscript, "Indexing roles of fact types in #{@join_steps.size} join steps" do
+        debug :subscript, "Indexing roles of fact types in #{join.all_join_step.size} join steps" do
           join_steps = []
           # Register all references to each join node as being for the same player:
           join.all_join_node.sort_by{|jn| jn.ordinal}.each do |join_node|
-            role_refs_have_same_player(join_node.all_role_ref.to_a)
-            join_steps += join_node.all_join_step_as_input_join_node.to_a + join_node.all_join_step_as_output_join_node.to_a 
+            debug :subscript, "Adding Roles of #{join_node.describe}" do
+              join_roles_have_same_player(join_node.all_join_role.to_a)
+              join_steps = join_steps | join_node.all_join_step
+            end
           end
+
+=begin
           # For each fact type traversed, register a player for each role *not* linked to this join
           # REVISIT: Using the preferred_reading role_ref is wrong here; the same preferred_reading might occur twice,
           # so the respective concept will need more than one Player and will be subscripted to keep them from being joined.
           # Accordingly, there must be a join step for each such role, and to enforce that, I raise an exception here on duplication.
-          join_steps.map{|js|js.fact_type}.uniq.each do |fact_type|
+          # This isn't needed now all JoinNodes have at least one JoinRole
+
+          join_steps.map do |js|
+            if js.fact_type.is_a?(ActiveFacts::Metamodel::ImplicitFactType)
+              js.fact_type.role.fact_type
+            else
+              js.fact_type
+            end
+          end.uniq.each do |fact_type|
+          #join_steps.map{|js|js.fact_type}.uniq.each do |fact_type|
             next if fact_type.is_a?(ActiveFacts::Metamodel::ImplicitFactType)
-            prrs = fact_type.preferred_reading.role_sequence.all_role_ref
-            residual_roles = fact_type.all_role.select{|r| !r.all_role_ref.detect{|rr| rr.join_node && rr.join_node.join == join} }
-            residual_roles.each do |r|
-              debug :subscript, "Adding residual role for #{r.concept.name} not covered in join"
-              preferred_role_ref = prrs.detect{|rr| rr.role == r}
-              if p = @player_by_role_ref[preferred_role_ref] and !p.role_refs.include?(preferred_role_ref)
-                raise "Adding DUPLICATE residual role for #{r.concept.name} not covered in join"
+
+            debug :subscript, "Residual roles in '#{fact_type.default_reading}' are" do
+              prrs = fact_type.preferred_reading.role_sequence.all_role_ref
+              residual_roles = fact_type.all_role.select{|r| !r.all_role_ref.detect{|rr| rr.join_node && rr.join_node.join == join} }
+              residual_roles.each do |r|
+                debug :subscript, "Adding residual role for #{r.concept.name} (in #{fact_type.default_reading}) not covered in join"
+                preferred_role_ref = prrs.detect{|rr| rr.role == r}
+                if p = @player_by_role_ref[preferred_role_ref] and !p.role_refs.include?(preferred_role_ref)
+                  raise "Adding DUPLICATE residual role for #{r.concept.name} not covered in join"
+                end
+                role_refs_have_same_player([preferred_role_ref])
               end
-              role_refs_have_same_player([preferred_role_ref])
             end
           end
+=end
         end
       end
 
       def verbalise_over_role_sequence role_sequence, joiner = ' and ', role_proximity = :both
         @role_refs = role_sequence.is_a?(Array) ? role_sequence : role_sequence.all_role_ref.to_a
 
-        if jrr = role_refs.detect{|rr| rr.join_node}
-          return verbalise_join(jrr.join_node.join)
+        if jrr = role_refs.detect{|rr| rr.join_role}
+          return verbalise_join(jrr.join_role.join_node.join)
         end
 
         # First, figure out whether there's a join:
         join_over, joined_roles = *Metamodel.join_roles_over(role_sequence.all_role_ref.map{|rr|rr.role}, role_proximity)
 
-        fact_types = @role_refs.map{|rr| rr.role.fact_type}.uniq
+        role_by_fact_type = {}
+        fact_types = @role_refs.map{|rr| ft = rr.role.fact_type; role_by_fact_type[ft] ||= rr.role; ft}.uniq
         readings = fact_types.map do |fact_type|
           name_substitutions = []
-          reading = fact_type.preferred_reading
+          # Choose a reading that start with the (first) role which caused us to emit this fact type:
+          reading = fact_type.reading_preferably_starting_with_role(role_by_fact_type[fact_type])
           if join_over and      # Find a reading preferably starting with the joined_over role:
             joined_role = fact_type.all_role.select{|r| join_over.subtypes_transitive.include?(r.concept)}[0]
             reading = fact_type.reading_preferably_starting_with_role joined_role
@@ -295,46 +401,56 @@ module ActiveFacts
             next unless subscript = player.subscript
             debug :subscript, "Need to apply subscript #{subscript} to #{rr.role.concept.name}"
           end
-          role_refs = @player_by_role_ref.keys.select{|rr| rr.role.fact_type == fact_type}
-          expand_reading_text(nil, reading.text, reading.role_sequence, role_refs)
+          player_by_role = {}
+          @player_by_role_ref.keys.each{|rr| player_by_role[rr.role] = @player_by_role_ref[rr] if rr.role.fact_type == fact_type }
+          #role_refs = @player_by_role_ref.keys.select{|rr| rr.role.fact_type == fact_type}
+          expand_reading_text(nil, reading.text, reading.role_sequence, player_by_role)
           #reading.expand(name_substitutions)
         end
         joiner ? readings*joiner : readings
       end
 
       # Expand this reading (or partial reading, during contraction)
-      def expand_reading_text(step, text, role_sequence, role_refs = [])
+      def expand_reading_text(step, text, role_sequence, player_by_role = {})
+        if !player_by_role.empty? and !player_by_role.is_a?(Hash) || player_by_role.keys.detect{|k| !k.is_a?(ActiveFacts::Metamodel::Role)}
+          debugger
+          raise "Need to change this call to expand_reading_text to pass a role->join_node hash"
+        end
         rrs = role_sequence.all_role_ref_in_order
-        debug :subscript, "expanding #{text} with #{role_sequence.describe}" do
+        debug :subscript, "expanding '#{text}' with #{role_sequence.describe}" do
           text.gsub(/\{(\d)\}/) do
             role_ref = rrs[$1.to_i]
             # REVISIT: We may need to use the step's role_refs to expand the role players here, not the reading's one (extra adjectives?)
             # REVISIT: There's no way to get literals to be emitted here (value join step?)
 
+            player = player_by_role[role_ref.role]
+
+=begin
             rr = role_refs.detect{|rr| rr.role == role_ref.role} || role_ref
 
             player = @player_by_role_ref[rr] and subscript = player.subscript
             if !subscript and
               pp = @players.select{|p|p.concept == rr.role.concept} and
               pp.detect{|p|p.subscript}
-              raise "Internal error: Subscripted players (of the same concept #{p.concept.name}) when this player isn't subscripted"
+              # raise "Internal error: Subscripted players (of the same concept #{pp[0].concept.name}) when this player isn't subscripted"
             end
+=end
 
-            subscripted_player(rr, role_ref) +
+            subscripted_player(role_ref, player && player.subscript) +
               objectification_verbalisation(role_ref.role.concept)
           end
         end
       end
 
-      def subscripted_player role_ref, reading_role_ref = nil
-        if player = @player_by_role_ref[role_ref] and subscript = player.subscript
+      def subscripted_player role_ref, subscript = nil
+        if subscript
           debug :subscript, "Need to apply subscript #{subscript} to #{role_ref.role.concept.name}"
         end
         concept = role_ref.role.concept
         [
-          (reading_role_ref || role_ref).leading_adjective,
+          role_ref.leading_adjective,
           concept.name,
-          (reading_role_ref || role_ref).trailing_adjective
+          role_ref.trailing_adjective
         ].compact*' ' +
           (subscript ? "(#{subscript})" : '')
       end
@@ -352,11 +468,10 @@ module ActiveFacts
 
         @join_nodes = join.all_join_node.sort_by{|jn| jn.ordinal}
 
-        @join_steps = @join_nodes.map{|jn| jn.all_join_step_as_input_join_node.to_a + jn.all_join_step_as_output_join_node.to_a }.flatten.uniq
+        @join_steps = @join_nodes.map{|jn| jn.all_join_step }.flatten.uniq
         @join_steps_by_join_node = @join_nodes.
           inject({}) do |h, jn|
-            jn.all_join_step_as_input_join_node.each{|js| (h[jn] ||= []) << js}
-            jn.all_join_step_as_output_join_node.each{|js| (h[jn] ||= []) << js}
+            jn.all_join_step.each{|js| (h[jn] ||= []) << js}
             h
           end
       end
@@ -365,12 +480,12 @@ module ActiveFacts
       def step_completed(step)
         @join_steps.delete(step)
 
-        input_node = step.input_join_node
+        input_node = step.input_join_role.join_node
         steps = @join_steps_by_join_node[input_node]
         steps.delete(step)
         @join_steps_by_join_node.delete(input_node) if steps.empty?
 
-        output_node = step.output_join_node
+        output_node = step.output_join_role.join_node
         if (input_node != output_node)
           steps = @join_steps_by_join_node[output_node]
           steps.delete(step)
@@ -401,7 +516,7 @@ module ActiveFacts
           if next_step.is_objectification_step
             # if this objectification plays any roles (other than its FT roles) in remaining steps, use one of those first:
             fact_type = next_step.fact_type.role.fact_type
-            jn = [next_step.input_join_node, next_step.output_join_node].detect{|jn| jn.concept == fact_type.entity_type}
+            jn = [next_step.input_join_role.join_node, next_step.output_join_role.join_node].detect{|jn| jn.concept == fact_type.entity_type}
             sr = @join_steps_by_join_node[jn].reject{|t| t.fact_type.role and t.fact_type.role.fact_type == fact_type}
             next_step = sr[0] if sr.size > 0 
           end
@@ -417,15 +532,15 @@ module ActiveFacts
           # Find whether last role has no following text, and its ordinal
         (reading.text =~ /\{([0-9])\}$/) &&
           # This reading's RoleRef for that role:
-        (role_ref = reading.role_sequence.all_role_ref.detect{|rr| rr.ordinal == $1.to_i}) &&
+        (role_ref = reading.role_sequence.all_role_ref_in_order[$1.to_i]) &&
           # was that RoleRef for the upcoming node?
-        role_ref.role.all_role_ref.detect{|rr| rr.join_node == next_node}
+        role_ref.role.concept == next_node.concept
       end
 
       def reading_starts_with_node(reading, next_node)
         reading.text =~ /^\{([0-9])\}/ and
           role_ref = reading.role_sequence.all_role_ref.detect{|rr| rr.ordinal == $1.to_i} and
-          role_ref.role.all_role_ref.detect{|rr| rr.join_node == next_node}
+          role_ref.role.concept == next_node.concept
       end
 
       # The last reading we emitted ended with the object type name for next_node.
@@ -456,8 +571,8 @@ module ActiveFacts
             detect do |js|
               # The objectifying entity type should always be the input_join_node here, but be safe:
               js.is_objectification_step and
-                (objectified_node = js.input_join_node).concept == concept ||
-                (objectified_node = js.output_join_node).concept == concept
+                (objectified_node = js.input_join_role.join_node).concept == concept ||
+                (objectified_node = js.output_join_role.join_node).concept == concept
             end
           return ''
         end
@@ -471,7 +586,7 @@ module ActiveFacts
           @join_steps.
             detect{|js|
               js.is_objectification_step and
-                js.input_join_node.concept == concept || js.output_join_node.concept == concept
+                js.input_join_role.join_node.concept == concept || js.output_join_role.join_node.concept == concept
             }
           steps << other_step
           debug :join, "Emitting objectification step allows deleting #{other_step.describe}"
@@ -479,10 +594,17 @@ module ActiveFacts
         end
 
         # Find all references to roles in this objectified fact type which are relevant to the join nodes of these steps:
-        role_refs = steps.map{|step| [step.input_join_node, step.output_join_node].map{|jn| jn.all_role_ref.detect{|rr| rr.role.fact_type == concept.fact_type}}}.flatten.compact.uniq
+        player_by_role = {}
+        steps.each do |join_step|
+          join_step.all_join_role.to_a.map do |jr|
+            player_by_role[jr.role] = @player_by_join_role[jr]
+          end
+        end
+
+        # role_refs = steps.map{|step| [step.input_join_role.join_node, step.output_join_role.join_node].map{|jn| jn.all_role_ref.detect{|rr| rr.role.fact_type == concept.fact_type}}}.flatten.compact.uniq
 
         reading = concept.fact_type.preferred_reading
-        " (where #{expand_reading_text(objectification_step, reading.text, reading.role_sequence, role_refs)})" 
+        " (where #{expand_reading_text(objectification_step, reading.text, reading.role_sequence, player_by_role)})" 
       end
 
       def elided_objectification(next_step, fact_type, last_is_contractable, next_node)
@@ -499,27 +621,27 @@ module ActiveFacts
         # Find which role occurs last in the reading, and which Join Node is attached
         reading.text =~ /\{(\d)\}[^{]*\Z/
         last_role_ref = reading.role_sequence.all_role_ref_in_order[$1.to_i]
-        exit_node = @join_nodes.detect{|jn| jn.all_role_ref.detect{|rr| rr.role == last_role_ref.role}}
+        exit_node = @join_nodes.detect{|jn| jn.all_join_role.detect{|jr| jr.role == last_role_ref.role}}
         exit_step = nil
 
         while other_step =
           @join_steps.
             detect{|js|
               next unless js.is_objectification_step
-              next unless js.input_join_node.concept == fact_type.entity_type || js.output_join_node.concept == fact_type.entity_type
-              exit_step = js if js.output_join_node == exit_node
+              next unless js.input_join_role.join_node.concept == fact_type.entity_type || js.output_join_role.join_node.concept == fact_type.entity_type
+              exit_step = js if js.output_join_role.join_node == exit_node
               true
             }
           debug :join, "Emitting objectified FT allows deleting #{other_step.describe}"
           step_completed(other_step)
         end
-        [ reading, exit_step ? exit_step.input_join_node : exit_node, exit_step, last_is_contractable]
+        [ reading, exit_step ? exit_step.input_join_role.join_node : exit_node, exit_step, last_is_contractable]
       end
 
       def verbalise_join join
         prepare_join join
         readings = ''
-        next_node = @role_refs[0].join_node   # Choose a place to start
+        next_node = @role_refs[0].join_role.join_node   # Choose a place to start
         last_is_contractable = false
         debug :join, "Join Nodes are #{@join_nodes.map{|jn| jn.describe }.inspect}, Join Steps are #{@join_steps.map{|js| js.describe }.inspect}" do
           until @join_steps.empty?
@@ -535,25 +657,17 @@ module ActiveFacts
                 end
 
             if next_step
-              debug :join, "Chose #{next_step.describe} because it's contractable against last node #{next_node.all_role_ref.to_a[0].role.concept.name} using #{next_reading.expand}"
-
-              step_ft = next_step.fact_type.is_a?(ActiveFacts::Metamodel::ImplicitFactType) ? next_step.fact_type.role.fact_type : next_step.fact_type
-              step_role_refs =   # for the two join nodes of this step, get the relevant role_refs for roles in this fact type
-                [next_step.input_join_node, next_step.output_join_node].
-                  uniq.
-                  map{|jn| jn.all_role_ref.select{|rr| rr.role.fact_type == step_ft } }.
-                  flatten.uniq
-              readings += expand_contracted_text(next_step, next_reading, step_role_refs)
+              debug :join, "Chose #{next_step.describe} because it's contractable against last node #{next_node.concept.name} using #{next_reading.expand}"
+
+              player_by_role =
+                next_step.all_join_role.inject({}) {|h, jr| h[jr.role] = @player_by_join_role[jr]; h }
+              readings += expand_contracted_text(next_step, next_reading, player_by_role)
               step_completed(next_step)
             else
               next_step = choose_step(next_node) if !next_step
 
-              step_ft = next_step.fact_type.is_a?(ActiveFacts::Metamodel::ImplicitFactType) ? next_step.fact_type.role.fact_type : next_step.fact_type
-              step_role_refs =   # for the two join nodes of this step, get the relevant role_refs for roles in this fact type
-                [next_step.input_join_node, next_step.output_join_node].
-                  uniq.
-                  map{|jn| jn.all_role_ref.select{|rr| rr.role.fact_type == step_ft } }.
-                  flatten.uniq
+              player_by_role =
+                next_step.all_join_role.inject({}) {|h, jr| h[jr.role] = @player_by_join_role[jr]; h }
 
               if next_step.is_unary_step
                 # Objectified unaries get emitted as unaries, not as objectifications:
@@ -561,28 +675,34 @@ module ActiveFacts
                 rr = next_step.input_join_node.all_role_ref.detect{|rr| rr.role.fact_type.is_a?(ImplicitFactType) }
                 next_reading = rr.role.fact_type.role.fact_type.preferred_reading
                 readings += " and " unless readings.empty?
-                readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, step_role_refs)
+                readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, player_by_role)
                 step_completed(next_step)
               elsif next_step.is_objectification_step
                 fact_type = next_step.fact_type.role.fact_type
+
+                # This objectification step is over an implicit fact type, so player_by_role won't have all the players
+                # Add the players of other roles associated with steps from this objectified player.
+                objectified_node = next_step.input_join_role.join_node
+                raise "Assumption violated that the objectification is the input join role" unless objectified_node.concept.fact_type
+                objectified_node.all_join_step.map do |other_step|
+                  (other_step.all_incidental_join_role.to_a + [other_step.output_join_role]).map do |jr|
+                    player_by_role[jr.role] = @player_by_join_role[jr]
+                  end
+                end
+
                 if last_is_contractable and next_node.concept.is_a?(EntityType) and next_node.concept.fact_type == fact_type
                   # The last reading we emitted ended with the name of the objectification of this fact type, so we can contract the objectification
-#                  if (n = next_step.input_join_node).concept == fact_type.entity_type ||
-#                    (n = next_step.output_join_node).concept == fact_type.entity_type
-#                    debugger
-#                    p n.concept.name  # This is the join_node which has the role_ref (and subscript!) we should use for the objectification_verbalisation
-#                  end
-                  # REVISIT: Do we need to use step_role_refs here (if this objectification is traversed twice and so is subscripted)
+                  # REVISIT: Do we need to use player_by_role here (if this objectification is traversed twice and so is subscripted)
                   readings += objectification_verbalisation(fact_type.entity_type)
                 else
                   # This objectified fact type does not need to be made explicit.
                   next_reading, next_node, next_step, last_is_contractable =
                     *elided_objectification(next_step, fact_type, last_is_contractable, next_node)
                   if last_is_contractable
-                    readings += expand_contracted_text(next_step, next_reading, step_role_refs)
+                    readings += expand_contracted_text(next_step, next_reading, player_by_role)
                   else
                     readings += " and " unless readings.empty?
-                    readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, step_role_refs)
+                    readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, player_by_role)
                   end
                   # No need to continue if we just deleted the last step
                   break if @join_steps.empty?
@@ -593,21 +713,19 @@ module ActiveFacts
                 # Prefer a reading that starts with the player of next_node
                 next_reading = fact_type.all_reading_by_ordinal.
                   detect do |reading|
-                    reading.text =~ /^\{([0-9])\}/ and
-                      role_ref = reading.role_sequence.all_role_ref.detect{|rr| rr.ordinal == $1.to_i} and
-                      role_ref.role.all_role_ref.detect{|rr| rr.join_node == next_node}
+                    reading_starts_with_node(reading, next_node)
                   end || fact_type.preferred_reading
                 # REVISIT: If this join step and reading has role references with adjectives, we need to expand using those
                 readings += " and " unless readings.empty?
-                readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, step_role_refs)
+                readings += expand_reading_text(next_step, next_reading.text, next_reading.role_sequence, player_by_role)
                 step_completed(next_step)
               end
             end
 
             # Continue from this step with the node having the most steps remaining
-            input_steps = @join_steps_by_join_node[next_step.input_join_node] || []
-            output_steps = @join_steps_by_join_node[next_step.output_join_node] || []
-            next_node = input_steps.size > output_steps.size ? next_step.input_join_node : next_step.output_join_node
+            input_steps = @join_steps_by_join_node[input_node = next_step.input_join_role.join_node] || []
+            output_steps = @join_steps_by_join_node[output_node = next_step.output_join_role.join_node] || []
+            next_node = input_steps.size > output_steps.size ? input_node : output_node
             # Prepare for possible contraction following:
             last_is_contractable = next_reading && node_contractable_against_reading(next_node, next_reading)