 
 #
 class Mutator extends Iterator
+  # For the current leaf page, give the mutator permission to peek at the right
+  # sibling leaf page if an insert determines that a records key is greater than
+  # the largest record in the current page. The record may belong in a right
+  # sibling page. Peeking at the next page is the only way to resolve the
+  # ambiguity, but loading a leaf has a cost, so we 
+  #
+  # If the insert index of the record is after the last record, but we do not
+  # have permission to peek at the right sibling leaf page to determine if it is
+  # less than the first element of the right sibling, the insert location is
+  # ambiguous and `insert` returns `null`.
+
+  # 
   peek: ->
     peeking = @_peek is @count
     @_peek = @count
     peeking
 
-  # TODO We've decided against duplicates, but I don't see us freaking out when
-  # we match a duplicate. This would be easier if we freaked out.
+  # Insert the object into the leaf. Returns the index where the object was
+  # inserted in the current leaf page if successful. Returns the bitwise
+  # compliment of the location of a record with same key, if a record with the
+  # same key already exists in the current leaf page.
+  #
+  # If the insert index of the record is after the last record, but we do not
+  # have permission to peek at the right sibling leaf page to determine if it is
+  # less than the first element of the right sibling, the insert location is
+  # ambiguous and `insert` returns `null`.
+  #
+  # If the insert index of the record is after the last record, and upon peeking
+  # at the first record of the right sibling leaf page we determine that the
+  # record belongs on a subsequent page, `insert` return `null`.
+  #
+  # An exception is raised if the record belongs in a page that is a left
+  # sibling leaf page of the current leaf page.
+
+  #  &mdash;
   insert: (object, _) ->
     if object instanceof Cassette
       { key, record } = object
     else
       [ record, key ]  = [ object, @_io.extractor object ]
 
-    # If we are at the first page and the key is equal to the key that created
-    # the mutator, than this is the correct leaf page for the record.
+    # If we are at the first leaf page and the key is the search key that got us
+    # here, then this is, without a doubt, the correct leaf page for the record.
     unambiguous = @count is 1 and @key and @_io.comparator(@key, key) is 0
 
     if unambiguous

    # TODO Should not be an else.
    else if index >= 0
      if not unambiguous and @_peek is @count
        unless unambiguous = page.next is -1
          @_next or= @_io.lock @_page.right, @_exclusive, true, _
          unambiguous = @_io.compare(key, @_io.key(@_next, 0, _)) < 0


# A mutator is an iterator that can also edit leaf pages. It can delete records
# from the currently visit leaf page. It can insert records into the current
# leaf page, if the record belongs in the current leaf page.
#
# As with `Iterator`, it moves across the leaf pages of an the b&#x2011;tree in
# ascending collation order. It has random access to the records in the page
# using an index into the array of records.
#
# As with `Iterator`, the application developer obtains an iterator by calling
# `Strata.mutator` with a search key.
#
# #### Ranged Inserts
#
# You can insert a range of records using a single mutator. This is efficient if
# you have a range of records whose keys are close together, maybe so close that
# they are all on the same page, so you can descend the tree to the correct page
# and insert them in one fell swoop.
#
# #### Ambiguous Insert Locations
# 
# Insert locations for ranged inserts can be ambiguous if the binary search
# indicates that a record should be inserted at the end of the leaf page, after
# the current last record in the leaf page. If the insert location is after the
# last record, it could be the case that the record really belongs to a right
# sibling leaf page.
#
# This is only a problem when we insert a record whose key is not the key used
# to create the mutator. An insert location is always unambiguous if the key is
# the search key used to locate the first page. The key is determined to belong
# inside the leaf page by virtue of a desent of the b&#x2011;tree. That is
# unambiguous.
#
# To know if a subsequent record insert really does belong after the last record
# but before the first record of the right sibling leaf page, we have to load
# the right sibling leaf page and peek at the record. When we do this, we need
# to keep the right sibling leaf page locked, so that the key of the right
# sibling page cannot change.
#
# This peek has a cost. If you are inserting a range, and the records are more
# often pages apart from each other than they are on the same page, it might not
# be worth it to peek. It might be more efficient to assume that a the next
# record is much futher along and create a new mutator for the remainder of the
# insert range. In this case we're saying, see if you can insert the next record
# on this page as long as we're here, but we leaf traversal is innefficent for
# our range,  so don't try too hard.
#
# If she is only inserting a single record, there's no ambiguity, because she'll
# use the key of the record to create the mutator. There is no need to enable
# peek for a single insert, but there is no real cost either.
#
# #### Duplicate Keys
#
# Although duplicate keys are not allowed, abstracted duplicate keys are not
# difficult for the application developer to implement given a mutator. The
# application developer can move forward through a series and append a record
# that has one greater than the maximum record.  Not a problem to worry about
# ambiguity in this case. Ah, we need to peek though, because we need to get
# that number.
#
# TK Fix.
#
# In fact, given a key plus a maximum series value, you will always land after
# the last one the series, or else a record that is less than the key, which
