ocaps meet normal code flow

README.org

@@ -766,8 +766,7 @@ the long term.
 Incremental improvement is better than no improvement at all, and
 there is a lot we can make better.
 
-* How to build it
+* Understanding object capabilities (ocaps)
-** Object capabilities (ocaps)
 
 The foundation of our system will be object capabilities
 (ocaps).
@@ -777,7 +776,13 @@ Ocaps are authority-by-possession: holding onto them is what gives
 you the power to invoke (use) them.
 If you don't have a reference to an ocap, you can't invoke it.
 
-*** Extending the car key metaphor
+Before we learn [[*How to build it][how to build]] a network of consent, we should
+make sure we learn to think about how an ocap system works.
+There are many ways to build ocaps, but before we show the
+(very simple) way we'll be building ours, let's make sure we wrap
+our heads around the paradigm a bit better.
+
+** Extending the car key metaphor
 
 We equated this to car keys before; the car doesn't care who you
 are, it only cares that you turn it on using the car key.
@@ -827,8 +832,74 @@ And yet ocap systems easily do give us this power.
 We will take advantage of this power to construct the systems we want
 and need.
 
-*** Principle of Least Authority meets normal code flow
+** Ocaps meet normal code flow
 
+The nice thing about object capabilities is that they permit the
+"Principle of Least Authority": we can hand only as much authority
+as is needed to complete a task.
+
+We saw this earlier, in contrast to solitaire.
+If we thought about solitaire as being a procedure, in contemporary
+operating systems, running it would look like so:
+
+#+BEGIN_SRC javascript
+// Runs with the full "ambient authority" of the user.
+// We don't need to pass in permissions, because it can already
+// do everything... but that includes crypto-lockering our
+// hard drive, uploading our cryptographic keys and passwords,
+// and deleting our data.
+solitaire();
+#+END_SRC
+
+By contrast, the ocap route would look like so:
+
+#+BEGIN_SRC javascript
+// We explicitly pass in the ability to read input from the
+// keyboard while the window has focus, to draw to the window,
+// and to read/write from a specific file.
+solitaire(getInput, writeToScreen, scoreFileAccess);
+#+END_SRC
+
+In fact, Jonathan Rees showed that
+[[http://mumble.net/~jar/pubs/secureos/secureos.html][ocaps are just everyday programming]], and with a few adjustments
+programming languages can be turned into ocap systems.[fn:whats-an-object]
+(For example, instead of modules reaching out and grabbing whatever
+they want to import, we can explicitly pass in access just as we pass
+in arguments to a function.)
+
+This may seem overwhelming.
+How do ocaps get to all the right places then?
+Thinking about ocaps as normal programming flow suddenly makes things
+make more sense: how do values that come from all the way on /that/
+side of our program get all the way to /this/ side of our program?
+It turns out that most data passed around in programs doesn't come from
+ambient user environments or global variables, it comes from normal
+argument passing.
+This should help us increase our confidence that we can use ocaps without
+them being a burdensome part of our programming workflows; they are,
+in fact, very similar to how we program every day.
+
+[fn:whats-an-object] You may have been wondering, does the word
+  "object" in "object capabilities" mean that our programs have to be
+  particularly "object oriented"?
+  First of all, no, ocaps can be implemented in what contemporarily
+  may be perceived as very non-OO functional systems.
+  Second, [[http://www.mumble.net/~jar/articles/oo.html][object oriented]] is a very vague term.
+  Third, "object capabilities" used to be just called "capabilities",
+  but other computing systems started to implement things which they
+  called "capabilities" which have nothing to do with the original
+  definition of "capabilities" (eg, Linux's kernels are closer to ACLs
+  than they are ocaps), so the name "object capability" was chosen to
+  distinguish between the two.
+
+** Ocaps meet human relationships
+
+
+** The power of proxying
+
+
+* How to build it
+** Ocaps we can use in our protocols
 
 *** Ocaps as capability URLs
 
@@ -838,15 +909,8 @@ That's all good and well, but real-world metaphors
 
 *** Ocaps meet ActivityPub objects/actors
 
-** Delegation, attenuation, revocation, composition, accountability
-
-# and composition?
-
-
 ** True names, public profiles, private profiles
 
-** Accountability and revocation in an ocap system
-
 ** Rights amplification and group-style permissions
 
 ** MultiBox vs sharedInbox