updated %clay doc

main/app/chat/core.hook

@@ -130,9 +130,9 @@
   ==
 ::
 ++  pour
-  |=  [ost=bone pax=path sih=*]
+  |=  [ost=bone pax=path sih=sign]
   ^-  [(list move) _+>]
-  =+  sih=((hard sign) sih)
+  ::  =+  sih=((hard sign) sih)
   ::  ~&  [%chat-pour sih]
   ?.  ?=([@ *] pax)  ~&  %chat-pour-strange-path  !!
   ?>  ?=(%g -.sih)

main/pub/src/doc/ref/vol/4c.md

@@ -123,6 +123,16 @@ these ducts.  The values are a description of the requested information.
 This represents a subscription request for a desk.  The request can be for
 either a single item in the desk or else for a range of changes on the desk.
 
+###`++rove`, stored general subscription request
+
+```
+++  rove  (each mood moot)                              ::  stored request
+```
+
+When we store a request, we store subscriptions with a little extra information
+so that we can determine whether new versions actually affect the path we're
+subscribed to.
+
 ###`++mood`, single subscription request
 
 ```
@@ -136,12 +146,23 @@ specifies the path we are requesting.
 ###`++moat`, range subscription request
 
 ```
-++  moat  ,[p=case q=case]                              ::  change range
+++  moat  ,[p=case q=case r=path]                       ::  change range
 ```
 
-This represents a request for all changes between `p` and `q`.  Note that there
+This represents a request for all changes between `p` and `q` on path `r`.  You
-is currently no way to request to be notified only on changes to particular
+will be notified when a change is made to the node referenced by the path or to
-paths in the filesystem.  You must subscribe to the entire desk.
+any of its children.
+
+###`++moot`, stored range subscription request
+
+```
+++  moot  ,[p=case q=case r=path s=(map path lobe)]     ::
+```
+
+This is just a `++moat` plus a map of paths to lobes.  This map represents the
+data at the node referenced by the path at case `p`, if we've gotten to that
+case (else null).  We only send a notification along the subscription if the
+data at a new revision is different than it was.
 
 ###`++care`, clay submode
 
@@ -613,7 +634,8 @@ subscription).  `r.p` is the desk.  `q` is the path to the filesystem node.
 ```
 
 This is the data that is produced by a request for a range of revisions of a
-desk.
+desk.  This allows us to easily keep track of a remote repository -- all the
+new information we need is contained in the `nako`.
 
 `gar` is a map of the revisions in the range to the hash of the commit
 at that revision.  These hashes can be used with `hut:rang` to find the commit
@@ -1389,22 +1411,25 @@ rave.  If the head was `&`, then it was a single request, so we handled it
 above.  If `|`, then we handle it with the following code.
 
 ```
-          |
         =+  nab=(~(aeon ze lim dom ran) p.p.rav)
         ?~  nab
           ?>  =(~ (~(aeon ze lim dom ran) q.p.rav))
-          (duce hen rav)
+          (duce hen (rive rav))
         =+  huy=(~(aeon ze lim dom ran) q.p.rav)
         ?:  &(?=(^ huy) |((lth u.huy u.nab) &(=(0 u.huy) =(0 u.nab))))
           (blub hen)
         =+  top=?~(huy let.dom u.huy)
-        =+  fud=(~(gack ze lim dom ran) u.nab let.dom)
+        =+  sar=(~(apax ze lim dom ran) u.nab r.p.rav)
-        =.  +>.$  (bleb hen u.nab fud)
+        =+  ear=(~(apax ze lim dom ran) top r.p.rav)
+        =.  +>.$
+          ?:  =(sar ear)  +>.$
+          =+  fud=(~(gack ze lim dom ran) u.nab top)
+          (bleb hen u.nab fud)
         ?^  huy
           (blub hen)
         =+  ^=  ptr  ^-  case
             [%ud +(let.dom)]
-        (duce hen `rave`[%| ptr q.p.rav])
+        (duce hen `rove`[%| ptr q.p.rav r.p.rav ear])
       ==
 ```
 
@@ -1416,7 +1441,7 @@ Thus, we first check to see if we've even gotten to the beginning of the range
 of revisions requested.  If not, then we assert that we haven't yet gotten to
 the end of the range either, because that would be really strange.  If not,
 then we immediately call `++duce`, which, if you recall, for a local request,
-simply puts this duct and rave into our cult `qyx`, so that we know who to
+simply puts this duct and rove into our cult `qyx`, so that we know who to
 respond to when the revision does appear.
 
 If we've already gotten to the first revision, then we can produce some content
@@ -1424,18 +1449,21 @@ immediately.  If we've also gotten to the final revision, and that revision is
 earlier than the start revision, then it's a bad request and we call `++blub`,
 which tells the subscriber that his subscription will not be satisfied.
 
-Otherwise, we call `++gack`, which creates the `++nako` we need to produce.  We
+Otherwise, we find the data at the given path at the beginning of the
-call `++bleb` to actually produce the information.  If we already have the last
+subscription and at the last available revision in the subscription.  If
-requested revision, then we also tell the subscriber with `++blub` that the
+they're the same, then we don't send a notification.  Otherwise, we call
-subscription will receive no further updates.
+`++gack`, which creates the `++nako` we need to produce.  We call `++bleb` to
+actually produce the information.
 
-If there will be more revisions, that we'll need to report, then we call
+If we already have the last requested revision, then we also tell the
-`++duce`, adding the duct to our subscribers.  We modify the rave to start at
+subscriber with `++blub` that the subscription will receive no further updates.
-the next revision since we've already handled all the revisions up to the
-present.
 
-We glossed over the calls to `++gack` and `++bleb`, so we'll get back to those
+If there will be more revisions in the subscription, then we call `++duce`,
-right now.  `++bleb` is simple, so we'll start with that.
+adding the duct to our subscribers.  We modify the rove to start at the next
+revision since we've already handled all the revisions up to the present.
+
+We glossed over the calls to `++apax`, `++gack`, and `++bleb`, so we'll get
+back to those right now.  `++bleb` is simple, so we'll start with that.
 
 ```
     ++  bleb                                          ::  ship sequence
@@ -1449,6 +1477,39 @@ the updates since that revision.  We use `++blab` to produce this result to
 the subscriber.  The case is `%w` with a revision number of the beginning of the
 subscription, and the data is the nako itself.
 
+We call `++apax:ze` to get the data at the particular path.
+
+```
+  ++  apax                                              ::    apax:ze
+    |=  [oan=@ud pax=path]                              ::  data at path
+    ^-  (map path lobe)
+    ?:  =(0 oan)  ~
+    %-  mo
+    %+  skim
+      %.  ~
+      %~  tap  by
+      =<  q
+      %-  ~(got by hut)
+      %-  ~(got by hit)
+      oan
+    |=  [p=path q=lobe]
+    ?|  ?=(~ pax)
+        ?&  !?=(~ p)
+            =(-.pax -.p)
+            $(p +.p, pax +.pax)
+    ==  ==
+```
+
+At revision zero, the theoretical common revision between all repositories,
+there is no data, so we produce null.
+
+We get the list of paths (paired with their lobe) in the revision referred to
+by the given number and we keep only those paths which begin with `pax`.
+Converting to a map, we now have a map from the subpaths at the given path to
+the hash of their data.  This is simple and efficient to calculate and compare
+to later revisions.  This allows us to easily tell if a node or its children
+have changed.
+
 Finally, we will describe `++gack:ze`.
 
 ```
@@ -1466,23 +1527,17 @@ Finally, we will describe `++gack:ze`.
     &((gth p a) (lte p b))
 ```
 
+We need to produce four things -- the numbers of the new commits, the number of
+the latest commit, the new commits themselves, and the new data itself.
 
+The first is fairly easy to produce.  We simply go over our map of numbered
+commits and produce all those numbered greater than `a` and not greater than
+`b`.
 
-```
+The second is even easier to produce -- `b` is clearly our most recent commit.
-  ++  hack                                            ::  trivial
-    |=  [a=(set tako) b=(set lobe)]
-    ^-  [(set yaki) (set blob)]
-    :-  %-  sa  %+  turn  (~(tap by a) ~)
-        |=  tak=tako
-        (need (~(get by hut) tak))
-    %-  sa  %+  turn  (~(tap by b) ~)
-    |=  lob=lobe
-    (need (~(get by lat) lob))
-```
 
-The type signature says everything you need to know about this.  We take a set
+The third and fourth are slightly more interesting, though not too terribly
-of hashes of commits and data and convert them into the actual commits and data
+difficult.  First, we call `++pack`.
-in the most straightforward way possible.
 
 ```
   ++  pack
@@ -1508,6 +1563,28 @@ in the most straightforward way possible.
     ^$(yak (need (~(get by hut) yek)))
 ```
 
+We take a possible starting commit and a definite ending commit, and we produce
+the set of commits and the set of data between them.
+
+We let `sar` be the set of commits reachable from `a`.  If `a` is null, then
+obviously no commits are reachable.  Otherwise, we call `++zule` to calculate this.
+
+```
+  ++  hack                                            ::  trivial
+    |=  [a=(set tako) b=(set lobe)]
+    ^-  [(set yaki) (set blob)]
+    :-  %-  sa  %+  turn  (~(tap by a) ~)
+        |=  tak=tako
+        (need (~(get by hut) tak))
+    %-  sa  %+  turn  (~(tap by b) ~)
+    |=  lob=lobe
+    (need (~(get by lat) lob))
+```
+
+The type signature says everything you need to know about this.  We take a set
+of hashes of commits and data and convert them into the actual commits and data
+in the most straightforward way possible.
+
 ```
   ++  zule                                            ::  reachable
     |=  p=tako                                        ::  XX slow