@@ -5,14 +5,15 @@ template = "doc.html"
55+++
66
77This 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,
9−we recommend reading and attempting to understand the data structures used in
10−any Hoon code before you try to read the code itself. Although complete
11−understanding of the data structures is impossible without seeing them used in
12−the code, an 80% understanding greatly clarifies the code. As another general
13−guide, when reading Hoon, it rarely pays off to understand every line of code
14−when it appears. Try to get the gist of it, and then move on. The next time you
15−come back to it, it'll likely make a lot more sense.
8+filesystem. It is up to date as of March 2021.
9+
10+As a general guide, we recommend reading and attempting to understand the data
11+structures used in any Hoon code before you try to read the code itself.
12+Although complete understanding of the data structures is impossible without
13+seeing them used in the code, an 80% understanding greatly clarifies the code.
14+As another general guide, when reading Hoon, it rarely pays off to understand
15+every line of code when it appears. Try to get the gist of it, and then move on.
16+The next time you come back to it, it'll likely make a lot more sense.
1617
1718### Data Models
1819
@@ -23,11 +24,11 @@ at least skimming, this so that you get a rough idea of how our state is
2324organized.
2425
2526The 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−(possibly in that order). All in all, though, this section isn't too
28−long, so many readers may wish to quickly read through all of it. If you
29−get bored, though, just skip to the next section. You can always come
30−back when you need to.
27+`++dome:clay`, `++ankh:clay`, `++rung:clay`, `++rang:clay`, `++blob:clay`,
28+`++yaki:clay`, and `++nori:clay` (possibly in that order). All in all, though,
29+this section isn't too long, so many readers may wish to quickly read through
30+all of it. If you get bored, though, just skip to the next section. You can
31+always come back when you need to.
3132
3233### `++raft`, formal state
3334
@@ -38,20 +39,43 @@ back when you need to.
3839 ran=rang :: hashes
3940 == ::
4041```
42+```hoon
43++$ raft :: filesystem
44+ $: rom=room :: domestic
45+ hoy=(map ship rung) :: foreign
46+ ran=rang :: hashes
47+ mon=(map term beam) :: mount points
48+ hez=(unit duct) :: sync duct
49+ cez=(map @ta crew) :: permission groups
50+ pud=(unit [=desk =yoki]) :: pending update
51+ == ::
52+```
4153
42−This is the state of our vane. Anything that must be remembered between
43−calls to clay is stored in this state.
44−
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.
54+This is the state of the vane. Anything that must be remembered between
55+calls to Clay is stored in this state.
5056
5157`ran` is the store of all commits and deltas, keyed by hash. The is
5258where all the "real" data we know is stored; the rest is "just
5359bookkeeping".
5460
61+`rom` is our domestic state. It consists of a `duct` to
62+[Dill](@/docs/arvo/dill/dill.md) and a collection of `desk`s.
63+
64+`hoy` is a collection of foreign ships for which we know something about their
65+Clay.
66+
67+`ran` is the object store. It has maps of commit hashes to commits and content
68+hashes to content.
69+
70+`mon` is a collection of Unix mount points. `term` is the mount point (relative
71+to th pier) and `beam` is a domestic Clay directory.
72+
73+`hez` is the Unix duct that `%ergo` `%gift`s should be sent to.
74+
75+`cez` is a collection of named permission groups.
76+
77+`pud` is an update that's waiting on a kernel upgrade.
78+
5579#### `++room`, filesystem per domestic ship
5680
5781```hoon
@@ -161,10 +185,10 @@ represents the data at the node referenced by the path at case `p`, if
161185we've gotten to that case (else null). We only send a notification along
162186the subscription if the data at a new revision is different than it was.
163187
164−### `++care:clay`, clay submode
188+### `++care:clay`, Clay submode
165189
166190```hoon
167− ++ care ?(%u %v %w %x %y %z) :: clay submode
191+ ++ care ?(%u %v %w %x %y %z) :: Clay submode
168192```
169193
170194This specifies what type of information is requested in a subscription
@@ -547,7 +571,7 @@ is not a complicated type; it is not difficult to work out the meaning.
547571 == ::
548572```
549573
550−This describes a change that we are asking clay to make to the desk.
574+This describes a change that we are asking Clay to make to the desk.
551575There are two kinds of changes that may be made: we can modify files or
552576we can apply a label to a commit.
553577
@@ -604,7 +628,7 @@ commits or data need be here.
604628
605629This represents a request for data about a particular desk. If `q`
606630contains 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
631+data. If `q` is null, then this tells Clay to cancel the subscription
608632along this duct.
609633
610634#### `++riot:clay`, response
@@ -698,7 +722,7 @@ request change. For the format of the requested change, see the
698722documentation for `++nori:clay` above.
699723
700724When 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
725+kiss. This tells Clay that the duct over which the kiss was sent is the
702726duct that unix is listening on for changes. From within Arvo, though, we
703727should never send a `%into` kiss. The `%info` kiss is exactly identical
704728except it does not reset the duct.
@@ -711,7 +735,7 @@ except it does not reset the duct.
711735
712736These kisses are currently identical to `%info` and `%into`, though this
713737will 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
738+typed changes to Clay so that we may store typed data. This is currently
715739unimplemented.
716740
717741```hoon