 #
 # This documentation assumes that you understand the theory behind the b-tree,
 # and know the variations of implementation. If you are interested in learning
-# about b-trees, this document could be a learning aid for you, but you should
-# start with the Wikipedia articles on
+# about b-trees you should start with the Wikipedia articles on
 # [B-trees](http://en.wikipedia.org/wiki/B-tree) and
-# [B+trees](http://en.wikipedia.org/wiki/B%2B_tree). 
+# [B+trees](http://en.wikipedia.org/wiki/B%2B_tree). I was introduced to b-trees
+# while reading [Algorithms in C](http://www.amazon.com/dp/0201314525), quite
+# some time ago.
 #
 # ## What flavor of b-tree is this?
 #
 # Strata is a b-tree with leaf pages that contain records ordered by the
-# collation order of the tree, indexed for retrieval in constant time, so that
-# they can be found using binary search. Branch pages contain links to other
-# pages, and do not store records themselves. Leaf pages are linked in ascending
-# order to ease the implementation of cursors.
-#
-# There is a maximum size for a page, that limits the number of links, in the
-# case of branch pages, or records in the case of leaf pages. When the maximum
-# size is reached which point a node is split. When two sibling pages next to
-# each other contain keys or records that combined are the less than than
-# maximum size they are merged.
-#
-# The tree always has a root branch page. The order of the tree increases when
-# the root branch is split. It decreases when the root branch is merged. The
-# split of the root branch is a different operation from the split of a non-root
-# branch, because the root branch does not have siblings.
-#
-# ## Implementation
+# collation order of the tree. Records are stored for retrieval in constant
+# time, addressed by an integer index, so that they can be found using binary
+# search.
+#
+# Branch pages contain links to other pages, and do not store records
+# themselves.
+#
+# Leaf pages are linked in ascending order for traversal by cursors. Brance
+# pages are singly linked in ascending order to simplify implementation of
+# branch pages merges.
+#
+# The page order is the maximum number of children for a branch page, or the
+# maximum number of records for a leaf page. When a page exceeds its capacity it
+# is split into two pages. When two sibling pages next to each other can be
+# combined to create a page less than than maximum size they are merged.
+#
+# The b-tree always has a root branch page. The order of the tree increases when
+# the root branch page is split. It decreases when the root branch page is
+# merged. The split of the root branch is a different operation from the split
+# of a non-root branch, because the root branch does not have siblings.
+#
+# ## Storage
+#
+# A database is a directory on the file system. Each page in the b-tree is
+# stored in a file in the file system.
+#
+# Our page implementations use JavaScript arrays of references to objects on
+# disk. The arrays sort the referneces according to the collation order of the
+# pages or records they reference. When we read records and keys off of disk, we
+# store them in an object that acts as a cache for the page.
+#
+# On disk and in memory, this arrangement is inheriently sparse. Pages are
+# stored in their own file, so they are no larger than they need to be on disk.
+#
+# JavaScript array implemenations are [clever about memory
+# usage](http://stackoverflow.com/questions/614126/why-is-array-push-sometimes-faster-than-arrayn-value/614255#614255)
+# and the per-page record cache is a hash table.
+#
+# ## Pages
+#
+# Every page has a page address. The page address is an integer. We reference
+# pages by this address. We write a page on disk into a file whose filename is
+# a prefix with the integer address appended. When we defererence a page we
+# either read it from a cache, or else we format the filename for the page and
+# read it from disk into the cache. Then we read it from cache.
 #
 # The b-tree has two types of pages. Leaf pages and branch pages.
 #
 # ### Leaf Pages
 #
-# Leaf pages contain records.
+# A leaf page contain records.
 #
 # In the abstract, a leaf page is an array data structure with zero based
 # integer index. The elements of the structure contain records. Given an

# to create relationship indexes. You can use Strata to store what ever form of
# JSON suits your needs like NoSQL databases.
#
# It runs anywhere that Node.js runs, in pure JavaScript.
#
# Maybe you need a database server, or maybe Strata is all you need to get your
# next application growing.
#
# ## Terminology
#


# ## Descent
#
# We use the term *descent* to describe b-tree operations, because all b-tree
# operations require a descent of the b-tree, a traversal of the b-tree starting
# from the root. Whenever we are search the tree, insert or delete records, or
# balance the tree with a page splits and merges, we first begin with a descent
# of the b-tree, from the root, to find the page we want to act upon.
#
# #### Descent as Unit of Work
#
# We use the term descent to describe the both traversal of the b-tree and the
# subsequent actions performed when when the desired page is found.
# 
# The descent is the unit of work in our concurrency model.  A descent is
# analogous to a thread, because when a descent waits on I/O, other descents can
# make progress.
#
# Descents can make progress concurrently, even though Node.js only has a single
# thread of execution. Descents do not actually make progress in parallel, but
# their progress can be interleaved. When we descend the tree, we may have to
# wait for evented I/O to read or write a page. While we wait, we can make
# progress on another descent in the main thread of execution.
#
# Because descents can make interleaved progress, we need to synchronize access
# to b-tree pages, just as we would with a multi-threaded b-tree implementation.
# When we descend the b-tree we need to make sure that we do not alter pages
# that another waiting descent needs to complete its descent when it awakes, nor
# read pages that a waiting descent had begun to alter before it had to wait.
#
# These are race conditions. We use the shared read/exclusive write locks
# described in the `IO` class above to guard against these race conditions.
#
# #### Classes of Descent
#
# When we descend to leaf pages of a search b-tree to obtain records, we
# *search* the b-tree. When we change the size of the b-tree by adding or
# deleting records we *edit* the b-tree. When we change the structure of the
# b-tree by splitting or merging pages, we *balance* the b-tree.
#
# We talk about search descents, edit descents, and balance descents we we
# describe the interaction of b-tree operations.
#
# We use these terms in this document to save the chore of writing, and the
# confustion of reading; insert or delete, or split or merge. We also want to
# draw a distinction between changing the count of records stored in the b-tree,
# *editing*, and changing the height of the b-tree, the count of pages, or the
# choice of keys, *balancing*.
#
# #### Locking on Descent
#
