Merge pull request #18 from dckc/ocap-doc

precise definition of ocap discipline

CONTRIBUTING.md

@@ -1,35 +1,68 @@
-## Protobuf Encoding: protobuf.js
-All of our protobuf encoding and decoding is done using [protobuf.js](https://github.com/dcodeIO/protobuf.js)
+# Code Conventions and Design Notes
+
+All contributions should pass these checks (as noted in
+`.travis.yml`):
+
+```yaml
+  - npm test
+  - npm run flow-check
+  - npm run lint
+```
+
+The `test` check is conventional unit tests.
+
+
+## Static Typechecking: flow
+
+We use [flow](https://flow.org/) for static typing. The `npm run
+flow-check` script does a complete check and `npm run flow-status`
+does an incremental check.
 
-![protobuf.js diagram](https://camo.githubusercontent.com/f090df881cc6c82ecb7c5d09c9fad550fdfd153e/687474703a2f2f64636f64652e696f2f70726f746f6275662e6a732f746f6f6c7365742e737667)
 
 ## Code Style: airbnb
 
-We follow the airbnb style, mostly. Use:
+We follow the [Airbnb JavaScript Style Guide][asg], mostly. Use `npm
+run lint`.  See `.eslitrc.json` for additional details.
 
-    npm run lint
+[asg]: https://github.com/airbnb/javascript#readme
 
-See .eslitrc.json for additional details.
 
-## Object Capability Paradigm
+## Object capability (ocap) discipline
 
-We follow the object capability design pattern. Some background is available at http://www.erights.org/elib/capability/ode/
+In order to supporting robust composition and cooperation without
+vulnerability, code in this project should adhere to [object
+capability discipline][ocap].
 
-One illustrative example in the code is the signature for a creating a node instance
-```javascript
-function RNode(
-      grpc /*: typeof grpcT */,
-      endPoint /*: { host: string, port: number } */
-    )
-```
-In non-ocap style the `grpc` instance would not be passed in but we only allow our node to use authority that was explicitly given to it. Thus if it is to communicate over gRPC, we need to pass in the capability.
+  - **Memory safety and encapsulation**
+    - There is no way to get a reference to an object except by
+      creating one or being given one at creation or via a message; no
+      casting integers to pointers, for example. _JavaScript is safe
+      in this way._
 
-We also define the convenience method `def`
-```javascript
-const def = obj => Object.freeze(obj)
-```
-which is used to box up the methods associated with an object like the node instance.
+      From outside an object, there is no way to access the internal
+      state of the object without the object's consent (where consent
+      is expressed by responding to messages). _We use `def` (aka
+      `Object.freeze`) and closures rather than properties on `this`
+      to achieve this._
+
+  - **Primitive effects only via references**
+    - The only way an object can affect the world outside itself is
+      via references to other objects. All primitives for interacting
+      with the external world are embodied by primitive objects and
+      **anything globally accessible is immutable data**. There must be
+      no `open(filename)` function in the global namespace, nor may
+      such a function be imported. _It takes some discipline to use
+      modules in node.js in this way.  We use a convention
+      of only accessing ambient authority inside `if (require.main ==
+      module) { ... }`._
+
+[ocap]: http://erights.org/elib/capability/ode/ode-capabilities.html
+
+
+## Protobuf Encoding: protobuf.js
+All of our protobuf encoding and decoding is done using [protobuf.js](https://github.com/dcodeIO/protobuf.js)
 
+![protobuf.js diagram](https://camo.githubusercontent.com/f090df881cc6c82ecb7c5d09c9fad550fdfd153e/687474703a2f2f64636f64652e696f2f70726f746f6275662e6a732f746f6f6c7365742e737667)
 
 ##  Struggles with extracting API doc
 
@@ -47,9 +80,3 @@ We'd like to use these scripts in our `package.json`:
 
     "doc": "node ./node_modules/.bin/documentation build --github rnodeAPI.js -f html -o docs",
     "doc-watch": "node ./node_modules/.bin/documentation serve --watch --github rnodeAPI.js"
-
-## Static Typechecking: flow
-
-We use [flow](https://flow.org/) for static typing. You can test your code with `npm run flow-check`
-
-There is also `npm run flow-status`