Add a matching entity to the index.

        We have to maintain the constraints of the data layout:
            - `self.mismatch_unknown` must still contain all matched entities
            - each key of the index must mismatch all known matching entities except those this particular key
              explicitly includes

        For data layout description, see the class-level docstring.

        :param collections.Hashable entity: an object to be matching the values of `traits_indexed_by`
        :param list traits: a list of hashable values to index the object with

def add_match(self, entity, *traits):
        """
        Add a matching entity to the index.

        We have to maintain the constraints of the data layout:
            - `self.mismatch_unknown` must still contain all matched entities
            - each key of the index must mismatch all known matching entities except those this particular key
              explicitly includes

        For data layout description, see the class-level docstring.

        :param collections.Hashable entity: an object to be matching the values of `traits_indexed_by`
        :param list traits: a list of hashable values to index the object with
        """
        # The index traits of `traits_indexed_by` might have already been used to index some other entities. Those
        # relations are to be preserved. If the trait was not used to index any entity, we initialize them to mismatch
        # all matching entities known so far.
        for trait in traits:
            if trait not in self.index:
                self.index[trait] = self.mismatch_unknown.copy()

        # Now each known trait this entity is not matching, will explicitly mismatch currently added entity.
        for existing_trait in self.index:
            if existing_trait not in traits:
                self.index[existing_trait].add(entity)

        # From now on, any new matching or mismatching index will mismatch this entity by default.
        self.mismatch_unknown.add(entity)