 (ns blocks.store.file
-  "Block storage backed by files in nested directories. Each block is stored in
-  a separate file. File block stores may be constructed using the
-  `file://<path-to-root>` URI form.
+  "This store provides block storage backed by files in local directories. Each
+  block is stored in a separate file. File block stores may be constructed
+  using the `file://<path-to-root-dir>` URI form. Under the root directory, the
+  store keeps a block files in a subdirectory, alongside some layout metadata
+  and a directory.
+
+      $ROOT/meta.properties
+      $ROOT/blocks/111497df/35011497df3588b5a3...
+      $ROOT/landing/block.123456789.tmp
 
   In many filesystems, performance degrades as the number of files in a
   directory grows. In order to reduce this impact and make navigating the
-  blocks a bit more efficient, block files are stored in directories under the
-  store root. All path elements are lower-case hex-encoded bytes from the
-  multihash.
-
-  The directories under the root consist of the first four bytes of the
-  multihashes of the blocks stored in them. Within each directory, blocks are
-  stored in files whose names consist of the rest of their digests.
-
-  Thus, a block containing the content `foobar` would have the sha1 digest
-  `97df3501149...` and be stored under the root directory at:
-
-      root/111497df/35011497df3588b5a3...
+  blocks more efficient, block files are stored in multiple subdirectories
+  consisting of the first four bytes of the multihashes of the blocks stored in
+  them. Within each directory, blocks are stored in files whose names consist
+  of the rest of their digests.
 
   In addition to the blocks, a `meta.properties` file at the root holds
   information about the current storage layout for future-proofing. This

  (-erase!
    [this]
    (d/future
      (rm-r root)
      true)))



(defn- id->file
  "Determine the filesystem path for a block of content with the given hash
  identifier."
  ^File
  [^File root id]
  (let [hex (multihash/hex id)
        len (min (dec (count hex)) prefix-length)
        subdir (subs hex 0 len)
        fragment (subs hex len)]
    (io/file (blocks-dir root) subdir fragment)))


(defn- file->id
  "Reconstruct the hash identifier represented by the given file path. Returns
  nil if the file is not a proper block."
  [^File root ^File file]
  (let [prefix (str (blocks-dir root))
        path (.getPath file)
        hex (str/replace (subs path (inc (count prefix))) "/" "")]
    (if (re-matches #"[0-9a-fA-F]+" hex)
      (multihash/decode (hex/parse hex))
      (log/warnf "File %s did not form valid hex entry: %s" file hex))))


(defn- file->block
