docs: def _refine_downcheck(merge, aliases, min_goodness):
      """Prune the merge to avoid it covering up any entries which are below the
      merge insertion position.
  
      For example, in the (non-orthogonal) table::
  
          00001 -> N S
          00011 -> N S
          00100 -> N S
          00X00 -> N S
          XX1XX -> 3 5
  
      Merging the first four entries would generate the new key-mask ``00XXX``
      which would be inserted above the entry with the key-mask ``XX1XX``.
      However ``00XXX`` would stop the key ``00110`` from reaching its correct
      route, that is ``00110`` would be covered by ``00XXX``. To avoid this one
      could just abandon the merge entirely, but a better solution is to attempt
      to reduce the merge such that it no longer covers any entries below it.
  
      To do this we first identify the bits that ARE ``X`` s in the merged
      key-mask but which are NOT ``X`` s in the entry that we're covering. For
      this example this is the 3rd bit. We then look to remove from the merge any
      entries which are either ``X`` s in this position OR have the same value as
      in this bit as the aliased entry. As the 4th entry in the table has an
      ``X`` in this position we remove it, and as the 3rd entry has a ``1`` we
      also remove it.  For this example we would then consider merging only the
      first two entries, leading to a new key-mask pair of ``000X1`` which can be
      safely inserted between ``00X00`` and ``XX1XX``::
  
          00100 -> N S
          00X00 -> N S
          000X1 -> N S
          XX1XX -> 3 5
  
      Returns
      -------
      :py:class:`~.Merge`
          New merge with entries possibly removed. If the goodness of the merge
          ever drops below `min_goodness` then an empty merge will be returned.
      """
      # Operation
      # ---------
      # While the merge is still better than `min_goodness` we determine which
      # entries below it in the table it covers. For each of these covered
      # entries we find which bits are Xs in the merged entry and are NOT Xs in
      # the covered entry.
      #
      # For example:
      #
      #     Merged entry:      ...0XXX1...
      #     Covered entry:     ...010XX...
      #     Bits of interest:      ^^
      #     Label used below:      mn
      #
      # NOTE:
      #   The covered entry may be of lower generality than the prospective
      #   merged entry if it is contained within the aliases dictionary (e.g.,
      #   ...010XX... may be part of
      #   ``aliases = {...XXXXX...: {..., ...010XX..., ...}, ...})``
      #
      # In this case there are 2 bits of interest highlighted. These are bits in
      # the merge entry whose value can be set (by removing entries from the
      # merge) to avoid covering the covered entry. Whenever we have multiple
      # covered entries we care only about the entries with the fewest number of
      # ``settable`` bits because these most constrain which entries we may
      # remove from the merge to avoid covering up the lower entry.
      #
      # NOTE:
      #   * If there is only 1 ``settable`` bit then we are very constrained in
      #     terms of which entries must be removed from the merge to avoid
      #     covering a lower entry.
      #   * If there are no ``settable`` bits then we cannot possibly avoid
      #     covering the lower entry - the only correct action is to return an
      #     empty merge.
      #
      # Assuming that there were no covered entries without any ``settable`` bits
      # (that is ``stringency > 0``) then ``bits_and_vals`` contains pairs of
      # bits and boolean values which indicate which values need to be removed
      # from which bit positions to avoid covering up lower entries. If the
      # example above were the only covered entry then ``bits_and_vals`` would
      # contain ``(m, True)`` to indicate that all entries containing Xs or 1s in
      # the left-most bit of interest could be removed to avoid the covered entry
      # and ``(n, False)`` to indicate that all entries containing Xs or 0s in
      # the right-most bit of interest could be removed to avoid covering the
      # entry.
      #
      # NOTE:
      #   ``bits_and_vals`` consists of a set of options (e.g., we *could* remove
      #   all entries with Xs or 1s in bit ``m`` *or* we could remove all entries
      #   with Xs or 0s in bit ``n``, either would resolve the above covering).
      #
      # To determine which course of action to take we build a dictionary mapping
      # each of the pairs in ``bits_and_vals`` to the entries that would need to
      # be removed to "set" that bit in the merged entry. For example, we might
      # end up with:
      #
      #     options = {(m, True): {1, 4, 5},
      #                (n, False): {3, 7}}
      #
      # Indicating that we'd need to remove entries 1, 4 and 5 from the merge to
      # "set" the mth bit of the merged to 0 or that we'd need to remove entries
      # 3 and 7 to set the nth bit of the merged entry to set the nth bit to 1.
      #
      # NOTE:
      #   The boolean part of the pair indicates which value needs to be removed
      #   (True -> remove all 1s and Xs; False -> remove all 0s and Xs). If all
      #   Xs and 1s in a given bit position are removed from a merge then the
      #   merged entry is guaranteed to have a 0 in the bit position. Vice-versa
      #   removing all Xs and 0s in a given bit position from a merge will result
      #   in a merged entry with a 1 in that position.
      #
      # As we want to make our merges as large as possible we select the smallest
      # set of entries to remove from the merge from ``options``.
      #
      # The whole process is then repeated since:
      #   * we ignored covered entries with more ``settable`` bits there may
      #     still be covered entries below the merged entry
      #   * after removing entries from the merge the merged entry is of lower
      #     generality and is therefore nearer the top of the table so new
      #     entries may be have become covered
  
      # Set of bit positions
      all_bits = tuple(1 << i for i in range(32))
  
      # While the merge is still worth considering continue to perform the
      # down-check.
      while merge.goodness > min_goodness:
          covered = list(_get_covered_keys_and_masks(merge, aliases))
  
          # If there are no covered entries (the merge is valid) then break out
          # of the loop.
          if not covered:
              break
  
          # For each covered entry work out which bits in the key-mask pair which
          # are not Xs are not covered by Xs in the merge key-mask pair. Only
          # keep track of the entries which have the fewest bits that we could
          # set.
          most_stringent = 33  # Not at all stringent
          bits_and_vals = set()
          for key, mask in covered:
              # Get the bit positions where there ISN'T an X in the covered entry
              # but there IS an X in the merged entry.
              settable = mask & ~merge.mask
  
              # Count the number of settable bits, if this is a more stringent
              # constraint than the previous constraint then ensure that we
              # record the new stringency and store which bits we need to set to
              # meet the constraint.
              n_settable = sum(1 for bit in all_bits if bit & settable)
              if n_settable <= most_stringent:
                  if n_settable < most_stringent:
                      most_stringent = n_settable
                      bits_and_vals = set()
  
                  # Add this settable mask and the required values to the
                  # settables list.
                  bits_and_vals.update((bit, not (key & bit)) for bit in
                                       all_bits if bit & settable)
  
          if most_stringent == 0:
              # If are there any instances where we could not possibly change a
              # bit to avoid aliasing an entry we'll return an empty merge and
              # give up.
              merge = _Merge(merge.routing_table, set())
              break
          else:
              # Get the smallest number of entries to remove to modify the
              # resultant key-mask to avoid covering a lower entry. Prefer to
              # modify more significant bits of the key mask.
              remove = set()  # Entries to remove
              for bit, val in sorted(bits_and_vals, reverse=True):
                  working_remove = set()  # Holder for working remove set
  
                  for i in merge.entries:
                      entry = merge.routing_table[i]
  
                      if ((not entry.mask & bit) or
                              (bool(entry.key & bit) is (not val))):
                          # If the entry has an X in this position then it will
                          # need to be removed regardless of whether we want to
                          # set a 0 or a 1 in this position, likewise it will
                          # need to be removed if it is a 0 and we want a 1 or
                          # vice-versa.
                          working_remove.add(i)
  
                  # If the current remove set is empty or the new remove set is
                  # smaller update the remove set.
                  if not remove or len(working_remove) < len(remove):
                      remove = working_remove
  
              # Remove the selected entries from the merge
              merge = _Merge(merge.routing_table, merge.entries - remove)
      else:
          # NOTE: If there are no covered entries, that is, if the merge is
          # better than min goodness AND valid this `else` clause is not reached.
          # Ensure than an empty merge is returned if the above loop was aborted
          # early with a non-empty merge.
          merge = _Merge(merge.routing_table, set())
  
      return merge