journal for the websitejournal

1 files changed, 48 insertions, 0 deletions

diff --git a/lib/protocols/Journal.mli b/lib/protocols/Journal.mli
new file mode 100644
index 0000000..5f2e760
--- /dev/null
+++ b/lib/protocols/Journal.mli
@@ -0,0 +1,48 @@
+(** a directory that keeps its history. Every change to its bindings is
+    a commit: one or more names bound again together, numbered, with a
+    snapshot of every binding as it stood afterwards. Guards are shown a
+    commit before it lands and may refuse it; observers are told of it
+    after. *)
+type t
+
+(** bind [name] to [replacement], or unbind it when [None], provided it
+    is still bound to [expected]. *)
+type change = {name: string; expected: Handle.t option; replacement: Handle.t option}
+
+(** [snapshot] is a directory of the bindings as of the commit. *)
+type commit = {number: int; snapshot: Handle.t; changed: string list}
+
+(** what a guard is shown: the commit the proposal would follow and the
+    commit it would be. *)
+type proposal = {previous: commit; proposed: commit}
+
+type guard = proposal -> (unit, Concepts.Condition.condition) result
+type observer = commit -> unit
+
+class type implementation = object
+  (** [Ok None] when a name was no longer bound to what was expected;
+      [Error] when a guard refused. Either way nothing changes. *)
+  method commit : change list -> (commit option, Concepts.Condition.condition) result
+
+  method head : commit
+
+  (** every commit, the oldest first. *)
+  method history : commit list
+
+  (** install, replace or remove the guard or observer of that name. *)
+  method guard : string -> guard option -> unit
+
+  method observe : string -> observer option -> unit
+end
+
+val make : #implementation -> Handle.protocol
+val from : Handle.t -> t Handle.interface option
+val require : Handle.t -> (t Handle.interface, Concepts.Condition.condition) result
+
+val commit :
+  t Handle.interface -> change list -> (commit option, Concepts.Condition.condition) result
+
+val head : t Handle.interface -> commit
+val history : t Handle.interface -> commit list
+val guard : t Handle.interface -> string -> guard option -> unit
+val observe : t Handle.interface -> string -> observer option -> unit