@@ -5,14 +5,15 @@ template = "doc.html"
7This section will be reference documentation for the data types used by our
7This section will be reference documentation for the data types used by our
8−filesystem. Parts of it may be inaccurate as of March 2021. As a general guide,
8+filesystem. It is up to date as of April 2021.
9−we recommend reading and attempting to understand the data structures used in
10+As a general guide, we recommend reading and attempting to understand the data
10−any Hoon code before you try to read the code itself. Although complete
11+structures used in any Hoon code before you try to read the code itself.
11−understanding of the data structures is impossible without seeing them used in
12+Although complete understanding of the data structures is impossible without
12−the code, an 80% understanding greatly clarifies the code. As another general
13+seeing them used in the code, an 80% understanding greatly clarifies the code.
13−guide, when reading Hoon, it rarely pays off to understand every line of code
14+As another general guide, when reading Hoon, it rarely pays off to understand
14−when it appears. Try to get the gist of it, and then move on. The next time you
15+every line of code when it appears. Try to get the gist of it, and then move on.
15−come back to it, it'll likely make a lot more sense.
16+The next time you come back to it, it'll likely make a lot more sense.
17### Data Models
18### Data Models
@@ -23,191 +24,275 @@ at least skimming, this so that you get a rough idea of how our state is
25The types that are certainly worth reading are `++raft`, `++room`,
26The types that are certainly worth reading are `++raft`, `++room`,
26−`++dome:clay`, `++ankh:clay`, `++rung:clay`, `++rang:clay`, `++blob:clay`, `++yaki:clay`, and `++nori:clay`
27+`++dome:clay`, `++ankh:clay`, `++rung:clay`, `++rang:clay`, `++blob:clay`,
27−(possibly in that order). All in all, though, this section isn't too
28+`++yaki:clay`, and `++nori:clay` (possibly in that order). All in all, though,
28−long, so many readers may wish to quickly read through all of it. If you
29+this section isn't too long, so many readers may wish to quickly read through
29−get bored, though, just skip to the next section. You can always come
30+all of it. If you get bored, though, just skip to the next section. You can
30−back when you need to.
31+always come back when you need to.
32−### `++raft`, formal state
33+### `$raft`, formal state
35− ++ raft :: filesystem
36++$ raft :: filesystem
36− $: fat=(map ship room) :: domestic
37+ $: rom=room :: domestic
37− hoy=(map ship rung) :: foreign
38+ hoy=(map ship rung) :: foreign
38− ran=rang :: hashes
39+ ran=rang :: hashes
40+ mon=(map term beam) :: mount points
41+ hez=(unit duct) :: sync duct
42+ cez=(map @ta crew) :: permission groups
43+ pud=(unit [=desk =yoki]) :: pending update
42−This is the state of our vane. Anything that must be remembered between
47+This is the state of the vane. Anything that must be remembered between
43−calls to clay is stored in this state.
48+calls to Clay is stored in this state.
45−`fat` is the set of domestic servers. This stores all the information
46−that is specfic to a particular ship on this pier. The keys to this map
47−are the ships on the current pier. all the information that is specific
48−to a particular foreign ship. The keys to this map are all the ships
49−whose filesystems we have attempted to access through clay.
51`ran` is the store of all commits and deltas, keyed by hash. The is
50`ran` is the store of all commits and deltas, keyed by hash. The is
52where all the "real" data we know is stored; the rest is "just
51where all the "real" data we know is stored; the rest is "just
53bookkeeping".
52bookkeeping".
54+`rom` is the state for all local desks. It consists of a `duct` to
55+[Dill](@/docs/arvo/dill/dill.md) and a collection of `desk`s.
57+`hoy` is the state for all foreign desks.
59+`ran` is the global, hash-addressed object store. It has maps of commit hashes
60+to commits and content hashes to content.
62+`mon` is a collection of Unix mount points. `term` is the mount point (relative
63+to th pier) and `beam` is a domestic Clay directory.
65+`hez` is the duct used to sync with Unix.
67+`cez` is a collection of named permission groups.
69+`pud` is an update that's waiting on a kernel upgrade.
55−#### `++room`, filesystem per domestic ship
72+#### `$room`, filesystem per domestic ship
58− ++ room :: fs per ship
75++$ room :: fs per ship
59− $: hun=duct :: terminal duct
76+ $: hun=duct :: terminal duct
60− hez=(unit duct) :: sync duch
61− dos=(map desk dojo) :: native desk
77+ dos=(map desk dojo) :: native desk
65This is the representation of the filesystem of a ship on our pier.
81This is the representation of the filesystem of a ship on our pier.
67−`hun` is the duct we use to send messages to dill to display
83+`hun` is the duct we use to send messages to [Dill](@/docs/arvo/dill/dill.md) to
68−notifications of filesystem changes. Only `%note` gifts should be
84+display notifications of filesystem changes. Only `%note` `%gift`s should be
69−produced along this duct. This is set by the `%init` kiss.
85+produced along this `duct`. This is set by the `%init` `move`.
71−`hez`, if present, is the duct we use to send sync messages to unix so
72−that they end up in the pier unix directory. Only `%ergo` gifts should
73−be producd along this duct. This is set by `%into` and `%invo` kisses.
75`dos` is a well-known operating system released in 1981. It is also the
87`dos` is a well-known operating system released in 1981. It is also the
76−set of desks on this ship, mapped to their data.
88+set of `desk`s on this ship, mapped to their `desk` state.
78−#### `++desk`, filesystem branch
90+#### `$desk`, filesystem branch
81− ++ desk ,@tas :: ship desk case spur
93++$ desk @tas
84−This is the name of a branch of the filesystem. The default desks are
96+This is the name of a branch of the filesystem. The default `desk`s are `%home`
85−"arvo", "main", and "try". More may be created by simply referencing
97+and `%kids`. More may be created by simply referencing them. `desk`s have
86−them. Desks have independent histories and states, and they may be
98+independent histories and states, and they may be
87−merged into each other.
99+[merged](@/docs/arvo/clay/using.md#merging) into each other.
89−### `++dojo`, domestic desk state
101+### `$dojo`, domestic desk state
105+ $: qyx=cult :: subscribers
92− ++ dojo ,[p=cult q=dome] :: domestic desk state
106+ dom=dome :: desk state
107+ per=regs :: read perms per path
108+ pew=regs :: write perms per path
95−This is the all the data that is specific to a particular desk on a
112+This is the all the data that is specific to a particular `desk` on a domestic
96−domestic ship. `p` is the set of subscribers to this desk and `q` is the
113+ship. `qyx` is the set of subscribers to this `desk`, and `dom` is the data in
97−data in the desk.
114+the `desk`. `regs` are `(map path rule)`, and so `per` is a `map` of read
115+permissions by `path` and `pew` is a `map` of write permissions by `path`.
99−#### `++cult`, subscriptions
117+#### `$cult`, subscriptions
102− ++ cult (map duct rave) :: subscriptions
120++$ cult (jug wove duct)
105−This is the set of subscriptions to a particular desk. The keys are the
123+`cult`s keep track of subscribers. `wove`s are associated to requests, and each
106−ducts from where the subscriptions requests came. The results will be
124+`wove` is mapped to a set of `duct`s associated to subscribers who should be
107−produced along these ducts. The values are a description of the
125+notified when the request is filled/updated.
108−requested information.
110−#### `++rave:clay`, general subscription request
127+#### `$rave:clay`, general subscription request
113− ++ rave :: general request
130+ +$ rave :: general request
114− $% [& p=mood] :: single request
131+ $% [%sing =mood] :: single request
132+ [%next =mood] :: await next version
133+ [%mult =mool] :: next version of any
115− [| p=moat] :: change range
134+ [%many track=? =moat] :: track range
119−This represents a subscription request for a desk. The request can be
138+This represents a subscription request for a `desk`.
120−for either a single item in the desk or else for a range of changes on
123−### `++rove`, stored general subscription request
140+A `%sing` request asks for data at single revision.
125−```hoon
142+A `%next` request asks to be notified the next time there’s a change to the
126− ++ rove (each mood moot) :: stored request
143+specified file.
129−When we store a request, we store subscriptions with a little extra
145+A `%mult` request asks to be notified the next time there's a change to a
130−information so that we can determine whether new versions actually
146+specified set of files.
131−affect the path we're subscribed to.
148+A `%many` request asks to be notified on every change in a `desk` for a range of changes (including into the future).
133−#### `++mood:clay`, single subscription request
150+### `$rove`, stored general subscription request
136− ++ mood ,[p=care q=case r=path] :: request in desk
153+ +$ rove :: stored request
154+ $% [%sing =mood] :: single request
155+ [%next =mood aeon=(unit aeon) =cach] :: next version of one
156+ $: %mult :: next version of any
157+ =mool :: original request
158+ aeon=(unit aeon) :: checking for change
159+ old-cach=(map [=care =path] cach) :: old version
160+ new-cach=(map [=care =path] cach) :: new version
162+ [%many track=? =moat lobes=(map path lobe)] :: change range
139−This represents a request for the state of the desk at a particular
166+Like a `rave` but with provisions to store current versions for `%next` and `%many`.
140−commit, specfied by `q`. `p` specifies what kind of information is
167+Generally used when we store a request in our state somewhere. This is so that
141−desired, and `r` specifies the path we are requesting.
168+we can determine whether new versions actually affect the path we're subscribed to.
143−#### `++moat:clay`, range subscription request
171+#### `$mood:clay`, single subscription request
146− ++ moat ,[p=case q=case r=path] :: change range
174+ +$ mood [=care =case =path] :: request in desk
149−This represents a request for all changes between `p` and `q` on path
177+This represents a request for data related to the state of the `desk` at a
150−`r`. You will be notified when a change is made to the node referenced
178+particular commit, specfied by `case`. `care` specifies what kind of information
151−by the path or to any of its children.
179+is desired, and `path` specifies the path we are requesting.
153−### `++moot`, stored range subscription request
181+#### `$moat:clay`, range subscription request
156− ++ moot ,[p=case q=case r=path s=(map path lobe)] ::
184+ +$ moat [from=case to=case =path] :: change range
159−This is just a `++moat:clay` plus a map of paths to lobes. This map
187+This represents a request for all changes between `from` and `to` on `path`. You
160−represents the data at the node referenced by the path at case `p`, if
188+will be notified when a change is made to the node referenced by the `path` or to
161−we've gotten to that case (else null). We only send a notification along
189+any of its children.
162−the subscription if the data at a new revision is different than it was.
164−### `++care:clay`, clay submode
191+### `$care:clay`, Clay submode
167− ++ care ?(%u %v %w %x %y %z) :: clay submode
194+ +$ care ?(%a %b %c %d %e %f %p %r %s %t %u %v %w %x %y %z) :: clay submode
170This specifies what type of information is requested in a subscription
198This specifies what type of information is requested in a subscription
171or a scry.
199or a scry.
173−`%u` requests the `++rang:clay` at the current moment. Because this
201+`%a` build a Hoon file at a `path`.
174−information is not stored for any moment other than the present, we
202+
175−crash if the `++case:clay` is not a `%da` for now.
203+`%b` build a dynamically typed `mark` by name (a `$dais` mark-interface core).
205+`%c` build a dynamically typed `mark` conversion gate (a `$tube`) by "from" and
208+`%d` returns a `(set desk)` of the `desk`s that exist on your ship.
210+`%e` builds a statically typed `mark` by name (a `$nave` mark-interface core).
212+`%f` builds a statically typed mark converstion gate.
214+`%p` produces the permissions for a directory, returned as a `[dict:clay dict:clay]`.
216+`%r` requests the file in the same fashion as `%x`, but wraps the result in a `vase`.
218+`%s` has miscellaneous debug endpoints.
177−`%v` requests the `++dome:clay` at the specified commit.
220+`%t` produces a `(list path)` of descendent `path`s for a directory within a `yaki`.
179−`%w` requests the revsion number of the desk.
222+`%u` produces a `?` depending on whether or not the specified file exists. It
223+does not check any of its children.
181−`%x` requests the file at a specified path at the specified commit. If
225+`%v` requests the entire `dome` for a specified `desk` at a particular `aeon`.
182−there is no node at that path or if the node has no contents (that is,
226+When used on a foreign `desk`, this get us up-to-date to the requested version.
183−if `q:ankh` is null), then this produces null.
185−`%y` requests a `++arch` of the specfied commit at the specified path.
228+`%w` requests the revision number and date of the specified path, returned as a `cass:clay`.
187−`%z` requests the `++ankh` of the specified commit at the specfied path.
230+`%x` requests the file at a specified path at the specified commit, returned as
231+an `@`. If there is no node at that path or if the node has no contents (that
232+is, if `fil:ankh` is null), then this crashes.
234+`%y` requests an `arch` of the specfied commit at the specified path. It will
235+return the bunt of an `arch` if the file or directory is not found.
237+`%z` requests a recursive hash of a node and all its children, returned as a `@uxI`.
189−### `++arch`, shallow filesystem node
239+#### `$ankh`, filesystem node
192− ++ arch ,[p=@uvI q=(unit ,@uvI) r=(map ,@ta ,~)] :: fundamental node
242++$ ankh :: expanded node
244+ $: fil=(unit [p=lobe q=cage]) :: file
245+ dir=(map @ta ankh) :: folders
195−This is analogous to `++ankh:clay` except that the we have neither our
249+This is a recursive filesystem node type that can describe a whole tree of
196−contents nor the ankhs of our children. The other fields are exactly the
250+folders and files, with subtrees organized by path prefix. In Earth filesystems,
197−same, so `p` is a hash of the associated ankh, `u.q`, if it exists, is a
251+a node is a file xor a directory. On Mars, we're inclusive, so a node is a file
198−hash of the contents of this node, and the keys of `r` are the names of
252+ior a directory.
199−our children. `r` is a map to null rather than a set so that the
253+
200−ordering of the map will be equivalent to that of `r:ankh`, allowing
254+`fil` is the contents of this file, if any. `p.fil` is a hash of the
201−efficient conversion.
255+contents while `q.fil` is the data itself.
203−#### `++case:clay`, specifying a commit
257+`dir` is the set of children of this node. In the case of a pure file,
258+this is empty. The keys are the names of the children and the values
259+are, recursively, the nodes themselves.
262+### `$arch`, shallow filesystem node
206− ++ case :: ship desk case spur
265++$ arch (axil @uvI)
268+ [fil=(unit item) dir=(map @ta ~)]
271+An `arch` is a lightweight version of an `ankh` that only contains the hash
272+of the associated file and a `map` of child directories, but not the children of
275+The child directories are given by a `map` to null rather than a `set` so that the
276+ordering of the `map` will be the same as it is for an `axal`, allowing
277+efficient conversion for when the heavier node is needed.
281+ [fil=(unit item) dir=(map @ta $)]
284+#### `$case`, specifying a commit
207− $% [%da p=@da] :: date
288+ $% :: %da: date
208− [%tas p=@tas] :: label
289+ :: %tas: label
209− [%ud p=@ud] :: number
294+ [%ud p=@ud]
213A commit can be referred to in three ways: `%da` refers to the commit
298A commit can be referred to in three ways: `%da` refers to the commit
@@ -216,91 +301,66 @@ that was at the head on date `p`, `%tas` refers to the commit labeled
216all can be reduced down to a `%ud`, only numbered commits may be
301all can be reduced down to a `%ud`, only numbered commits may be
217referenced with a `++case:clay`.
302referenced with a `++case:clay`.
219−#### `++dome:clay`, desk data
304+#### `$dome`, desk data
222− ++ dome :: project state
307++$ dome
223− $: ang=agon :: pedigree
224− ank=ankh :: state
308+ $: ank=ankh :: state
225− let=@ud :: top id
309+ let=aeon :: top id
226− hit=(map ,@ud tako) :: changes by id
310+ hit=(map aeon tako) :: versions by id
227− lab=(map ,@tas ,@ud) :: labels
311+ lab=(map @tas aeon) :: labels
312+ mim=(map path mime) :: mime cache
313+ fod=ford-cache :: ford cache
314+ fer=(unit reef-cache) :: reef cache
231−This is the data that is actually stored in a desk.
318+A `dome` is the state of a `desk` and associated data.
233−`ang` is unused and should be removed.
235`ank` is the current state of the desk. Thus, it is the state of the
320`ank` is the current state of the desk. Thus, it is the state of the
236−filesystem at revison `let`. The head of a desk is always a numbered
321+filesystem at revison `let`. The head of a `desk` is always a numbered
239`let` is the number of the most recently numbered commit. This is also
324`let` is the number of the most recently numbered commit. This is also
240the total number of numbered commits.
325the total number of numbered commits.
242−`hit` is a map of numerical ids to hashes of commits. These hashes are
327+`hit` is a map of numerical ids to commit hashes. These hashes are mapped into
243−mapped into their associated commits in `hut:rang:clay`. In general, the keys
328+their associated commits in `hut.rang` in the `raft` of Clay. In general, the
244−of this map are exactly the numbers from 1 to `let`, with no gaps. Of
329+keys of this map are exactly the numbers from 1 to `let`, with no gaps. Of
245−course, when there are no numbered commits, `let` is 0, so `hit` is
330+course, when there are no numbered commits, `let` is 0, so `hit` is null.
246−null. Additionally, each of the commits is an ancestor of every commit
331+Additionally, each of the commits is an ancestor of every commit numbered
247−numbered greater than this one. Thus, each is a descendant of every
332+greater than this one. Thus, each is a descendant of every commit numbered less
248−commit numbered less than this one. Since it is true that the date in
333+than this one. Since it is true that the date in each commit (`t:yaki`) is no
249−each commit (`t:yaki`) is no earlier than that of each of its parents,
334+earlier than that of each of its parents, the numbered commits are totally
250−the numbered commits are totally ordered in the same way by both
251−pedigree and date. Of course, not every commit is numbered. If that
335+ordered in the same way by both pedigree and date. Of course, not every commit
252−sounds too complicated to you, don't worry about it. It basically
336+is numbered. If that sounds too complicated to you, don't worry about it. It
253−behaves exactly as you would expect.
337+basically behaves exactly as you would expect.
255`lab` is a map of textual labels to numbered commits. Note that labels
339`lab` is a map of textual labels to numbered commits. Note that labels
256can only be applied to numbered commits. Labels must be unique across a
340can only be applied to numbered commits. Labels must be unique across a
259−#### `++ankh`, filesystem node
343+`mim` is a cache of the content in the directories that are mounted to Unix.
261−```hoon
345+`fod` is the Ford cache, which keeps a cache of the results of builds performed
262− ++ ankh :: fs node (new)
346+at this `desk`'s current revision, including a full transitive closure of
263− $: p=cash :: recursive hash
347+dependencies for each completed build.
264− q=(unit ,[p=cash q=*]) :: file
265− r=(map ,@ta ankh) :: folders
269−This is a single node in the filesystem. This may be file or a directory
270−or both. In earth filesystems, a node is a file xor a directory. On
271−mars, we're inclusive, so a node is a file ior a directory.
273−`p` is a recursive hash that depends on the contents of the this file or
274−directory and on any children.
276−`q` is the contents of this file, if any. `p.q` is a hash of the
277−contents while `q.q` is the data itself.
279−`r` is the set of children of this node. In the case of a pure file,
280−this is empty. The keys are the names of the children and the values
281−are, recursively, the nodes themselves.
283−#### `++cash`, ankh hash
349+`fer` is the system file cache, which consists of `vase`s for `hoon.hoon`,
284−
350+`arvo.hoon`, `lull.hoon`, and `zuse.hoon`.
286− ++ cash ,@uvH :: ankh hash
289−This is a 128-bit hash of an ankh. These are mostly stored within ankhs
290−themselves, and they are used to check for changes in possibly-deep
293#### `++rung`, filesystem per neighbor ship
352#### `++rung`, filesystem per neighbor ship
296− ++ rung $: rus=(map desk rede) :: neighbor desks
356+ $: rus=(map desk rede) :: neighbor desks
300−This is the filesystem of a neighbor ship. The keys to this map are all
360+This is the filesystem of a neighbor ship. The keys to this `map` are all
301−the desks we know about on their ship.
361+the `desk`s we know about on their ship.
303−#### `++rede`, desk state
363+#### `++rede`, generic desk state
306 ++ rede :: universal project
366 ++ rede :: universal project
@@ -309,342 +369,312 @@ the desks we know about on their ship.
309 ref=(unit rind) :: outgoing requests
369 ref=(unit rind) :: outgoing requests
310 dom=dome :: revision state
370 dom=dome :: revision state
372++$ rede :: universal project
373+ $: lim=@da :: complete to
374+ ref=(unit rind) :: outgoing requests
375+ qyx=cult :: subscribers
376+ dom=dome :: revision state
377+ per=regs :: read perms per path
378+ pew=regs :: write perms per path
314This is our knowledge of the state of a desk, either foreign or
382This is our knowledge of the state of a desk, either foreign or
317−`lim` is the date of the last full update. We only respond to requests
385+`lim` is the most recent `@da` for which we're confident we have all the
318−for stuff before this time.
386+information for. For local `desk`s, this is always `now`. For foriegn `desk`s,
387+this is the last time we got a full update from the foreign ship.
320−`qyx` is the list of subscribers to this desk. For domestic desks, this
389+`ref` is the request manager for the desk. For domestic `desk`s, this is
321−is simply `p:dojo`, all subscribers to the desk, while in foreign desks
390+null since we handle requests ourselves. For foreign `desk`s, this keeps track
322−this is all the subscribers from our ship to the foreign desk.
391+of all pending foriegn requests plus a cache of the responses to previous requests.
324−`ref` is the request manager for the desk. For domestic desks, this is
393+`qyx` is the `set` of subscriptions to this desk, with listening `duct`s. These
325−null since we handle requests ourselves.
394+subscriptions exist only until they've been filled. For domestic `desk`s, this
395+is simply `qyx:dojo` - all subscribers to the `desk`. For foreign `desk`s this
396+is all the subscribers from our ship to the foreign `desk`.
327−`dom` is the actual data in the desk.
398+`dom` is the data in the `desk`.
400+`regs` are `(map path rule)`, and so `per` is a `map` of read permissions by
401+`path` and `pew` is a `map` of write permissions by `path`.
329−#### `++rind`, request manager
404+#### `$rind`, foreign request manager
332− ++ rind :: request manager
407++$ rind :: request manager
333− $: nix=@ud :: request index
408+ $: nix=@ud :: request index
334− bom=(map ,@ud ,[p=duct q=rave]) :: outstanding
409+ bom=(map @ud update-state) :: outstanding
335− fod=(map duct ,@ud) :: current requests
410+ fod=(map duct @ud) :: current requests
336− haw=(map mood (unit)) :: simple cache
411+ haw=(map mood (unit cage)) :: simple cache
340−This is the request manager for a foreign desk.
415+This is the request manager for a foreign `desk`. When we send a request to a
416+foreign ship, we keep track of it in here.
342−`nix` is one more than the index of the most recent request. Thus, it is
418+`nix` is one more than the index of the most recent request. Thus, it is the
343−the next available request number.
419+next available request number.
345−`bom` is the set of outstanding requests. The keys of this map are some
421+`bom` is the set of outstanding requests. The keys of this `map` are some subset
346−subset of the numbers between 0 and one less than `nix`. The members of
422+of the numbers between 0 and one less than `nix`. The members of the `map` are
347−the map are exactly those requests that have not yet been fully
423+exactly those requests that have not yet been fully satisfied.
350−`fod` is the same set as `bom`, but from a different perspective. In
425+`fod` is the same set as `bom`, but from a different perspective. In particular,
351−particular, the values of `fod` are the same as the values of `bom`, and
426+the values of `fod` are the same as the keys of `bom`, and the `duct` of the
352−the `p` out of the values of `bom` are the same as the keys of `fod`.
427+values of `bom` are the same as the keys of `fod`. Thus, we can map `duct`s to
353−Thus, we can map ducts to their associated request number and `++rave:clay`,
428+their associated request number and `update-state`, and we can map request
354−and we can map numbers to their associated duct and `++rave:clay`.
429+numbers to their associated `duct`.
356−`haw` is a map from simple requests to their values. This acts as a
431+`haw` is a map from `%sing` requests to their values. This acts as a cache for
357−cache for requests that have already been made. Thus, the second request
432+requests that have already been filled.
358−for a particular `++mood:clay` is nearly instantaneous.
360−#### `++rang:clay`, data store
434+#### `$update-state`, status of outstanding foreign request
440+ have=(map lobe blob)
442+ nako=(qeu (unit nako))
447+An `update-state` is used to represent the status of an outstanding request to a
450+`duct` and `rave` are the `duct` along which the request was made and the
453+`have` is a map of hashes thus far acquired in the request to the data
454+associated with those hashes.
456+`need` is a list of hashes yet to be acquired.
458+`nako` is a queue of data yet to be validated.
460+`busy` tracks whether or not the request is currently being fulfilled.
462+#### `$rang:clay`, data repository
465+ +$ rang :: repository
363− ++ rang $: hut=(map tako yaki) ::
466+ $: hut=(map tako yaki) :: changes
364− lat=(map lobe blob) ::
467+ lat=(map lobe blob) :: data
368−This is a set of data keyed by hash. Thus, this is where the "real" data
471+This is a data repository keyed by hash. Thus, this is where the "real" data
369is stored, but it is only meaningful if we know the hash of what we're
472is stored, but it is only meaningful if we know the hash of what we're
370looking for.
473looking for.
372−`hut` is a map from hashes to commits. We often get the hashes from
475+`hut` is a `map` from commit hashes (`tako`s) to commits (`yaki`s). We often get
373−`hit:dome:clay`, which keys them by logical id. Not every commit has an id.
476+the hashes from `hit:dome`, which keys them by numerical id. Not every commit
375−`lat` is a map from hashes to the actual data. We often get the hashes
479+`lat` is a `map` from content hashes (`lobe`s) to the actual content (`blob`s).
376−from a `++yaki`, a commit, which references this map to get the data.
480+We often get the hashes from a `yaki`, which references this `map` to get the
377−There is no `++blob:clay` in any `++yaki:clay`. They are only accessible through
481+data. There is no `blob` in `yaki:clay`. They are only accessible through
380−#### `++tako:clay`, commit reference
484+#### `$tako:clay`, commit reference
383− ++ tako ,@ :: yaki ref
487+ +$ tako @ :: yaki ref
386−This is a hash of a `++yaki:clay`, a commit. These are most notably used as
490+This is a hash of a `yaki:clay`, a commit. These are most notably used as the
387−the keys in `hut:rang:clay`, where they are associated with the actual
491+keys in `hut:rang:clay`, where they are associated with the actual `yaki:clay`,
388−`++yaki:clay`, and as the values in `hit:dome:clay`, where sequential ids are
492+and as the values in `hit:dome:clay`, where sequential numerical ids are
389associated with these.
493associated with these.
391−#### `++yaki:clay`, commit
495+#### `$yaki:clay`, commit
499+ $: p=(list tako) :: parents
394− ++ yaki ,[p=(list tako) q=(map path lobe) r=tako t=@da] :: commit
500+ q=(map path lobe) :: namespace
501+ r=tako :: self-reference
397This is a single commit.
506This is a single commit.
399−`p` is a list of the hashes of the parents of this commit. In most
508+`p` is a `list` of the hashes of the parents of this commit. In most
400cases, this will be a single commit, but in a merge there may be more
509cases, this will be a single commit, but in a merge there may be more
401parents. In theory, there may be an arbitrary number of parents, but in
510parents. In theory, there may be an arbitrary number of parents, but in
402practice merges have exactly two parents. This may change in the future.
511practice merges have exactly two parents. This may change in the future.
403For commit 1, there is no parent.
512For commit 1, there is no parent.
405−`q` is a map of the paths on a desk to the data at that location. If you
514+`q` is a `map` of the `path`s on a desk to the content hashes at that location.
406−understand what a `++lobe:clay` and a `++blob:clay` is, then the type signature
515+If you understand what a `lobe:clay` and a `blob:clay` is, then the type
407−here tells the whole story.
516+signature here tells the whole story.
409`r` is the hash associated with this commit.
518`r` is the hash associated with this commit.
411`t` is the date at which this commit was made.
520`t` is the date at which this commit was made.
413−#### `++lobe:clay`, data reference
522+#### `$lobe:clay`, data reference
416− ++ lobe ,@ :: blob ref
525+ +$ lobe @uvI :: blob ref
419−This is a hash of a `++blob:clay`. These are most notably used in `lat:rang:clay`,
528+This is a hash of a `blob:clay`. These are most notably used in `lat:rang:clay`,
420−where they are associated with the actual `++blob:clay`, and as the values in
529+where they are associated with the actual `blob:clay`, and as the values in
421−`q:yaki:clay`, where paths are associated with their data in a commit.
530+`q:yaki:clay`, where `path`s are associated with their content hashes in a commit.
423−#### `++blob:clay`, data
426− ++ blob $% [%delta p=lobe q=lobe r=udon] :: delta on q
427− [%direct p=lobe q=* r=umph] ::
428− [%indirect p=lobe q=* r=udon s=lobe] ::
432−This is a node of data. In every case, `p` is the hash of the blob.
434−`%delta` is the case where we define the data by a delta on other data.
435−In practice, the other data is always the previous commit, but nothing
436−depends on this. `q` is the hash of the parent blob, and `r` is the
439−`%direct` is the case where we simply have the data directly. `q` is the
532+#### `$blob:clay`, data
440−data itself, and `r` is any preprocessing instructions. These almost
441−always come from the creation of a file.
443−`%indirect` is both of the preceding cases at once. `q` is the direct
444−data, `r` is the delta, and `s` is the parent blob. It should always be
445−the case that applying `r` to `s` gives the same data as `q` directly
446−(with the prepreprocessor instructions in `p.r`). This exists purely for
447−performance reasons. This is unused, at the moment, but in general these
448−should be created when there are a long line of changes so that we do
449−not have to traverse the delta chain back to the creation of the file.
451−#### `++udon`, abstract delta
454− ++ udon :: abstract delta
535+ +$ blob :: fs blob
455− $: p=umph :: preprocessor
536+ $% [%delta p=lobe q=[p=mark q=lobe] r=page] :: delta on q
456− $= q :: patch
537+ [%direct p=lobe q=page] :: immediate
457− $% [%a p=* q=*] :: trivial replace
458− [%b p=udal] :: atomic indel
459− [%c p=(urge)] :: list indel
460− [%d p=upas q=upas] :: tree edit
465−This is an abstract change to a file. This is a superset of what would
540+This is a node of data. In both cases, `p` is the hash of the blob.
466−normally be called diffs. Diffs usually refer to changes in lines of
467−text while we have the ability to do more interesting deltas on
468−arbitrary data structures.
470−`p` is any preprocessor instructions.
472−`%a` refers to the trival delta of a complete replace of old data with
475−`%b` refers to changes in an opaque atom on the block level. This has
542+`%delta` is the case where we define the data by a delta on other data. In
476−very limited usefulness, and is not used at the moment.
543+practice, the other data is always the previous commit, but nothing depends on
544+this. `p.q` is the `mark` of the parent blob, `q.q` is the hash of the parent
545+blob, and `r` is the delta.
478−`%c` refers to changes in a list of data. This is often lines of text,
547+`%direct` is the case where we simply have the data directly. `q` is the data.
479−which is your classic diff. We, however, will work on any list of data.
548+These almost always come from the creation of a file.
481−`%d` refers to changes in a tree of data. This is general enough to
482−describe changes to any hoon [noun](/docs/glossary/noun/), but often more special-purpose delta
483−should be created for different content types. This is not used at the
484−moment, and may in fact be unimplemented.
486−#### `++urge`, list change
551+#### `+urge`, list change
489− ++ urge |*(a=_,* (list (unce a))) :: list change
554+ ++ urge |*(a=mold (list (unce a))) :: list change
492−This is a parametrized type for list changes. For example, `(urge ,@t)`
557+This is a parametrized type for list changes. For example, `(urge @t)`
493is a list change for lines of text.
558is a list change for lines of text.
495−#### `++unce`, change part of a list.
560+#### `+unce`, change part of a list.
498− ++ unce |* a=_,* :: change part
563+ ++ unce :: change part
499− $% [%& p=@ud] :: skip[copy]
565+ $% [%& p=@ud] :: skip[copy]
500− [%| p=(list a) q=(list a)] :: p -> q[chunk]
566+ [%| p=(list a) q=(list a)] :: p -> q[chunk]
504This is a single change in a list of elements of type `a`. For example,
570This is a single change in a list of elements of type `a`. For example,
505−`(unce ,@t)` is a single change in a lines of text.
571+`(unce @t)` is a single change in lines of text.
507`%&` means the next `p` lines are unchanged.
573`%&` means the next `p` lines are unchanged.
509`%|` means the lines `p` have changed to `q`.
575`%|` means the lines `p` have changed to `q`.
511−#### `++umph`, preprocessing information
514− ++ umph :: change filter
515− $| $? %a :: no filter
519− $% [%d p=@ud] :: blocklist
523−This space intentionally left undocumented. This stuff will change once
524−we get a well-typed clay.
526−#### `++upas`, tree change
529− ++ upas :: tree change (%d)
530− $& [p=upas q=upas] :: cell
531− $% [%0 p=axis] :: copy old
532− [%1 p=*] :: insert new
533− [%2 p=axis q=udon] :: mutate!
537−This space intentionally left undocumented. This stuff is not known to
538−work, and will likely change when we get a well-typed clay. Also, this
539−is not a complicated type; it is not difficult to work out the meaning.
541−#### `++nori:clay`, repository action
577+#### `$nori:clay`, repository action
544− ++ nori :: repository action
580+ +$ nori :: repository action
545− $% [& q=soba] :: delta
581+ $% [%& p=soba] :: delta
546− [| p=@tas] :: label
582+ [%| p=@tas] :: label
550−This describes a change that we are asking clay to make to the desk.
586+This describes a change that we are asking Clay to make to the `desk`.
551There are two kinds of changes that may be made: we can modify files or
587There are two kinds of changes that may be made: we can modify files or
552we can apply a label to a commit.
588we can apply a label to a commit.
554In the `|` case, we will simply label the current commit with the given
590In the `|` case, we will simply label the current commit with the given
555label. In the `&` case, we will apply the given changes.
591label. In the `&` case, we will apply the given changes.
557−#### `++soba:clay`, delta
593+#### `$soba:clay`, delta
560− ++ soba ,[p=cart q=(list ,[p=path q=miso])] :: delta
596+ +$ soba (list [p=path q=miso]) :: delta
563−This describes a set of changes to make to a desk. The `cart` is simply
599+This describes a `list` of changes to make to a `desk`. The `path`s are `path`s
564−a pair of the old hash and the new hash of the desk. The list is a list
565−of changes keyed by the file they're changing. Thus, the paths are paths
566−to files to be changed while `miso` is a description of the change
600+to files to be changed, and the corresponding `miso` value is a description of
567−itself.
601+the change itself.
569−#### `++miso:clay`, ankh delta
603+#### `$miso:clay`, ankh delta
572− ++ miso :: ankh delta
606+ +$ miso :: ankh delta
573− $% [%del p=*] :: delete
607+ $% [%del ~] :: delete
574− [%ins p=*] :: insert
608+ [%ins p=cage] :: insert
609+ [%dif p=cage] :: mutate from diff
575− [%mut p=udon] :: mutate
610+ [%mut p=cage] :: mutate from raw
579−There are three kinds of changes that may be made to a node in a desk.
614+There are four kinds of changes that may be made to a node in a `desk`.
580−We can insert a file, in which case `p` is the contents of the new file.
581−We can delete a file, in which case `p` is the contents of the old file.
582−Finally, we can mutate that file, in which case the `udon` describes the
583−changes we are applying to the file.
585−#### `++mizu:clay`, merged state
616+`%del` deletes the node.
587−```hoon
618+`%ins` inserts a file given by `p`.
588− ++ mizu ,[p=@u q=(map ,@ud tako) r=rang] :: new state
619+
589−```
620+`%dif` is currently unimplemented. This may seem strange, so we remark that
621+diffs for individual files are implemented using `+diff` and `+pact` in `mark`s.
622+So for an `ankh`, which may include both files and directories, `%dif` being
623+unimplemented really just means that we do not yet have a formal concept of
624+changes in directory structure.
591−This is the input to the `%merg` kiss, which allows us to perform a
626+`%mut` mutates the file using raw data given by `p`.
592−merge. The `p` is the number of the new head commit. The `q` is a map
593−from numbers to commit hashes. This is all the new numbered commits that
594−are to be inserted. The keys to this should always be the numbers from
595−`let.dom` plus one to `p`, inclusive. The `r` is the maps of all the new
596−commits and data. Since these are merged into the current state, no old
597−commits or data need be here.
599−#### `++riff:clay`, request/desist
628+#### `$riff:clay`, request/desist
602− ++ riff ,[p=desk q=(unit rave)] :: request/desist
631+ +$ riff [p=desk q=(unit rave)] :: request+desist
605−This represents a request for data about a particular desk. If `q`
634+This represents a request for data about a particular `desk`. If `q`
606−contains a `rave`, then this opens a subscription to the desk for that
635+contains a `rave`, then this opens a subscription to the `desk` for that
607−data. If `q` is null, then this tells clay to cancel the subscription
636+data. If `q` is null, then this tells Clay to cancel the subscription
608along this duct.
637along this duct.
610−#### `++riot:clay`, response
639+#### `$riot:clay`, response
613− ++ riot (unit rant) :: response/complete
642+ +$ riot (unit rant) :: response+complete
616−A riot is a response to a subscription. If null, the subscription has
645+A `riot` is a response to a subscription. If null, the subscription has
617been completed, and no more responses will be sent. Otherwise, the
646been completed, and no more responses will be sent. Otherwise, the
618`rant` is the produced data.
647`rant` is the produced data.
620−#### `++rant:clay`, response data
649+#### `$rant:clay`, response data
623− ++ rant :: namespace binding
652+ +$ rant :: response to request
624− $: p=[p=care q=case r=@tas] :: clade release book
653+ $: p=[p=care q=case r=desk] :: clade release book
625− q=path :: spur
654+ q=path :: spur
626− r=* :: data
655+ r=cage :: data
630−This is the data at a particular node in the filesystem. `p.p` specifies
659+This is the data associated to the response to a request. `p.p` specifies
631the type of data that was requested (and is produced). `q.p` gives the
660the type of data that was requested (and is produced). `q.p` gives the
632specific version reported (since a range of versions may be requested in
661specific version reported (since a range of versions may be requested in
633−a subscription). `r.p` is the desk. `q` is the path to the filesystem
662+a subscription). `r.p` is the `desk`. `q` is the path to the filesystem
634node. `r` is the data itself (in the format specified by `p.p`).
663node. `r` is the data itself (in the format specified by `p.p`).
636−### `++nako`, subscription response data
665+### `$nako`, subscription response data
668++$ nako :: subscription state
639− ++ nako $: gar=(map ,@ud tako) :: new ids
669+ $: gar=(map aeon tako) :: new ids
640− let=@ud :: next id
670+ let=aeon :: next id
641− lar=(set yaki) :: new commits
671+ lar=(set yaki) :: new commits
642− bar=(set blob) :: new content
672+ bar=(set plop) :: new content
646This is the data that is produced by a request for a range of revisions
676This is the data that is produced by a request for a range of revisions
647−of a desk. This allows us to easily keep track of a remote repository --
677+of a `desk`. This allows us to easily keep track of a remote repository --
648all the new information we need is contained in the `nako`.
678all the new information we need is contained in the `nako`.
650`gar` is a map of the revisions in the range to the hash of the commit
680`gar` is a map of the revisions in the range to the hash of the commit
@@ -656,105 +686,3 @@ revision number, whichever is smaller.
657`lar` is the set of new commits, and `bar` is the set of new content.
687`lar` is the set of new commits, and `bar` is the set of new content.
661−As with all vanes, there are exactly two ways to interact with clay.
662−`%clay` exports a namespace accessible through `.^`, which is described
663−above under `++care:clay`. The primary way of interacting with clay, though,
664−is by sending kisses and receiving gifts.
667− ++ gift :: out result <-$
668− $% [%ergo p=@p q=@tas r=@ud] :: version update
669− [%note p=@tD q=tank] :: debug message
670− [%writ p=riot] :: response
672− ++ kiss :: in request ->$
673− $% [%info p=@p q=@tas r=nori] :: internal edit
674− [%ingo p=@p q=@tas r=nori] :: internal noun edit
675− [%init p=@p] :: report install
676− [%into p=@p q=@tas r=nori] :: external edit
677− [%invo p=@p q=@tas r=nori] :: external noun edit
678− [%merg p=@p q=@tas r=mizu] :: internal change
679− [%wart p=sock q=@tas r=path s=*] :: network request
680− [%warp p=sock q=riff] :: file request
684−There are only a small number of possible kisses, so it behooves us to
685−describe each in detail.
688− $% [%info p=@p q=@tas r=nori] :: internal edit
690− [%into p=@p q=@tas r=nori] :: external edit
693−These two kisses are nearly identical. At a high level, they apply
694−changes to the filesystem. Whenever we add, remove, or edit a file, one
695−of these cards is sent. The `p` is the ship whose filesystem we're
696−trying to change, the `q` is the desk we're changing, and the `r` is the
697−request change. For the format of the requested change, see the
698−documentation for `++nori:clay` above.
700−When a file is changed in the unix filesystem, vere will send a `%into`
701−kiss. This tells clay that the duct over which the kiss was sent is the
702−duct that unix is listening on for changes. From within Arvo, though, we
703−should never send a `%into` kiss. The `%info` kiss is exactly identical
704−except it does not reset the duct.
707− [%ingo p=@p q=@tas r=nori] :: internal noun edit
709− [%invo p=@p q=@tas r=nori] :: external noun edit
712−These kisses are currently identical to `%info` and `%into`, though this
713−will not always be the case. The intent is for these kisses to allow
714−typed changes to clay so that we may store typed data. This is currently
718− [%init p=@p] :: report install
721−Init is called when a ship is started on our pier. This simply creates a
722−default `room` to go into our `raft`. Essentially, this initializes the
723−filesystem for a ship.
726− [%merg p=@p q=@tas r=mizu] :: internal change
729−This is called to perform a merge. This is most visibly called by
730−:update to update the filesystem of the current ship to that of its
731−sein. The `p` and `q` are as in `%info`, and the `r` is the description
732−of the merge. See `++mizu:clay` above.
735−`XX [%wake ~] :: timer activate XX`
737−XX This card is sent by unix at the time specified by `++doze`. This
738−time is XX usually the closest time specified in a subscription request.
739−When `%wake` is XX called, we update our subscribers if there have been
743− [%wart p=sock q=@tas r=path s=*] :: network request
746−This is a request that has come across the network for a particular
747−file. When another ship asks for a file from us, that request comes to
748−us in the form of a `%wart` kiss. This is handled by trivially turning
752− [%warp p=sock q=riff] :: file request
755−This is a request for information about a particular desk. This is, in
756−its most general form, a subscription, though in many cases it is the
757−trivial case of a subscription -- a read. See `++riff:clay` for the format of