a clean description of capabilities, their derivation, and naming conventions in tahoe

[Imported from Trac: page Capabilities, version 1]

Capabilities.md

@@ -0,0 +1,53 @@
+from the mailing list archives - [Feb 2009 - Brian Warner](http://allmydata.org/pipermail/tahoe-dev/2009-February/001110.html)
+
+```
+ 1: immutable file read-only capability string  URI:CHK:
+ 2: immutable file verify capability string     URI:CHK-Verifier:
+
+ 3: mutable file read-write capability string   URI:SSK:
+ 4: mutable file read-only capability string    URI:SSK-RO:
+ 5: mutable file verify capability string       URI:SSK-Verifier:
+
+ 6: directory read-write capability string      URI:DIR2:
+ 7: directory read-only capability string       URI:DIR2-RO:
+ 8: directory verify capability string          URI:DIR2-Verifier:
+
+In Tahoe, directories are built out of mutable files (a directory is really
+just a particular way to interpret the contents of a given mutable file), and
+non-directory mutable files aren't used very much. All normal data files are
+uploaded into immutable files by default.
+
+Some capabilities can be used to derive others. If you have #1, you can
+derive #2 (but not the other way around). The full table is:
+
+ #1->#2
+ #3->#4->#5
+ #6->#7->#8
+
+So we use "filecap" to talk about #1+#3+#4, but (since most files are
+immutable) we're usually talking about #1. We use "dircap" to talk about #6
+and #7. We use "readcap" to talk about #1,#4, and #7, but usually we refer to
+#7 as a "directory readcap". We use "writecap" to talk about #3 and #6.
+
+A "verifycap" is the weakest capability that still allows every bit of every
+share to be validated (hashes checked, signatures verified, etc). That means
+#2, #5, and #8.
+
+When we talk about a "repaircap", we mean "the weakest capability that can
+still be used to repair the file". Given the current limitations of the
+repairer and our webapi, that means we're talking about #1, #3, or #6.
+Eventually we'll fix this limitation, and any verifycap should be useable as
+a repaircap too. (there's much less work involved to let #2 repair a file..
+it's just an incomplete API, rather than a fundamental redesign of the server
+protocol).
+
+We then use the somewhat-vague term "rootcap" to refer to a cap (usually a
+directory write cap) that is not present inside any directory, so the only
+way to ever reach it is to remember it somewhere outside of Tahoe. It might
+be remembered in the allmydata.com rootcap database (indexed by account name
+plus password), or it might be remembered in a ~/.tahoe/private/aliases file,
+or it might just be written down on a piece of paper. The point is that you
+have to start from somewhere, and we refer to such a starting point as a
+"rootcap".
+
+```