 #  * Descent - What we call an attempt to move from a parent node to a child
 #              node in  the tree, which may be paused because it encounters a
 #              lock on a tier.
+#  * Record - A JSON object stored in the b-tree.
+#  * Object - JavaScript objects are referred to as objects in this
+#             documentation and are not to be confused with actual records.
 
 #              
 class Mutation

    @head.previous  = @head
    @nextAddress    = 0

  create: (_) ->
    try
      stat = fs.stat @directory, _
      if not stat.isDirectory()

        key = tierOrAddress.cache[address] = @key address, 0, _
      key

  # Write the branches to a file as a JSON string. We tuck the tier properties
  # into an object before we serialize it, so that it is easy deserialize.
  writeBranches: (tier, suffix, _) ->
    filename = @filename tier.address, suffix
    record = [ tier.penultimate, tier.next, tier.addresses ]
    json = JSON.stringify(record) + "\n"
    fs.writeFile filename, json, "utf8", _

  # Read branches from a brach tier file and assign the tier properties to the
  # given tier object.
  #
  # TODO: Move link to head always, to maintain MRU.
  readBranches: (tier, _) ->
    filename = @filename tier.address
    json = fs.readFile filename, "utf8", _
    [ penultimate, next, addresses ] = JSON.parse json
    extend tier, { penultimate, next, addresses }

  # TODO Consider: can't I always just rewrite and link?
  rewriteBranches: (tier, _) ->
    @writeBranches(tier, ".new", _)

