1 files changed, 52 insertions, 0 deletions
diff --git a/docs/journal.org b/docs/journal.org
new file mode 100644
index 0000000..f26f068
--- /dev/null
+++ b/docs/journal.org
@@ -0,0 +1,52 @@
+#+TITLE: Journals and derived relations
+
+Two protocols and two kernel modules let subsystems share state over time
+without linking each other. They stand in for what the branch manager will
+do once it records the bindings of a namespace.
+
+* Journal
+A journal (=Kernel.Journal=) is a namespace that keeps its history. It
+answers =Directory= and =Registry= as =Kernel.Namespace= does, so code that
+only knows those keeps working, and every binding it accepts is a commit:
+
+#+begin_src ocaml
+type commit = {number: int; snapshot: Handle.t; changed: string list}
+#+end_src
+
+=snapshot= is a directory of every binding as it stood after the commit.
+The =Journal= protocol adds:
+
+- =commit=: bind several names together, each provided it is still bound
+  to what was expected. Either all land or none does.
+- =guard=: a function shown each commit before it lands, with the commit it
+  would follow. Returning an error refuses it.
+- =observe=: a function told of each commit after it lands.
+
+Guards and observers run while the journal is held, so they see commits one
+at a time and in order. Neither may commit to the journal itself.
+
+=Kernel.Journal.adopt= makes a journal holding whatever a directory binds
+now. =Kernel.Journal.rebind= binds names in one commit when given a journal,
+and one at a time, retrying each swap, when given a plain namespace.
+
+* Derived
+A relation computed from other relations carries =Derived=:
+
+#+begin_src ocaml
+method within : Handle.t -> (Handle.t, condition) result
+#+end_src
+
+=within d= is the same relation read against the directory =d=. A snapshot
+applies it to whatever derived relation it hands out, with itself as =d=.
+So reading through a snapshot gives a derived relation as it was at that
+commit, or, for a commit a guard is still weighing, as it would be.
+
+=Kernel.View.computed= makes such a relation from a function of a directory,
+and =Kernel.View.fixed= one that never changes. =Kernel.View.read= reads a
+relation's heading and tuples whole.
+
+* Limits
+- History lives in memory and grows without bound.
+- A snapshot is named by its bindings, so two commits that bind the same
+  objects are the same snapshot.
+- A derived relation is computed again on every read.