From 7cbf0da4dbffef97575d43304cac23e61d891a78 Mon Sep 17 00:00:00 2001
From: davidsarah <>
Date: Thu, 1 Jul 2010 02:01:35 +0000
Subject: [PATCH] literal caps and immutable directories

[Imported from Trac: page Capabilities, version 5]
---
 Capabilities.md | 52 +++++++++++++++++++++++++++++--------------------
 1 file changed, 31 insertions(+), 21 deletions(-)

diff --git a/Capabilities.md b/Capabilities.md
index b134c81..b8135ab 100644
--- a/Capabilities.md
+++ b/Capabilities.md
@@ -1,18 +1,24 @@
 # Capabilities
 
-An overview from the mailing list archives - originally [Feb 2009 - Brian Warner](http://allmydata.org/pipermail/tahoe-dev/2009-February/001110.html):
+An overview from the mailing list archives - originally by [Feb 2009 - Brian Warner](http://allmydata.org/pipermail/tahoe-dev/2009-February/001110.html),
+but updated to take into account literal caps and immutable directories:
 
 ```
- 1: immutable file read-only capability string  URI:CHK:
- 2: immutable file verify capability string     URI:CHK-Verifier:
+ 1: immutable file read-only capability string            URI:CHK:
+ 2: immutable file verify capability string               URI:CHK-Verifier:
+ 3: immutable LIT file read-only capability string        URI:LIT:
 
- 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:
+ 4: mutable file read-write capability string             URI:SSK:
+ 5: mutable file read-only capability string              URI:SSK-RO:
+ 6: 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:
+ 7: immutable directory read-only capability string       URI:DIR2-CHK:
+ 8: immutable directory verify capability string          URI:DIR2-CHK-Verifier:
+ 9: immutable LIT directory read-only capability string   URI:DIR2-LIT:
+
+10: mutable directory read-write capability string        URI:DIR2:
+11: mutable directory read-only capability string         URI:DIR2-RO:
+12: mutable 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
@@ -22,28 +28,32 @@ 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
+ #1 -> #2
+ #4 -> #5 -> #6
+ #7 -> #8
+ #10-> #11-> #12
 
 Deriving a weaker capability from a strong one is called "diminishing" the stronger one.
 
-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.
+So we use "filecap" to talk about #1..6, but (since most files are immutable)
+we're usually talking about #1. We use "dircap" to talk about #7..12.
+We use "readcap" to talk about #{1,3,5,7,9,11}, but usually we refer to
+#{7,9,11} as a "directory readcap". We use "writecap" to talk about #4 and #10.
+
+A "literal cap" or "LIT cap" stores the contents of a small file (#3) or
+directory (#9) in the capability itself.
 
 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.
+#{2,6,8,12}.
 
 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.
+repairer and our webapi, that means we're talking about #{1,4,7,10}.
 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).
+a repaircap too. (There's much less work involved to let #2 repair a file or
+#8 repair a directory... 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