@@ -4,26 +4,25 @@ weight = 2
4template = "doc.html"
4template = "doc.html"
7−Clay is the primary filesystem for the [Arvo](/docs/arvo/overview) operating system,
7+Clay is the primary filesystem for the [Arvo](/docs/arvo/overview)
8−which is the [core](/docs/glossary/core/) of an urbit. The architecture of Clay is
8+operating system, which is the [core](/docs/glossary/core/) of an
9+urbit. The architecture of Clay is intrinsically connected with Arvo,
9−intrinsically connected with Arvo, but for this section we assume no knowledge of
10+but for this section we assume no knowledge of either Arvo or Urbit.
10−either Arvo or Urbit. We will point out only those features of
11+We will point out only those features of Arvo that are necessary for
11−Arvo that are necessary for an understanding of Clay, and we will
12−do so only when they arise.
12+an understanding of Clay, and we will do so only when they arise.
14The first relevant feature of Arvo is that it is a deterministic
14The first relevant feature of Arvo is that it is a deterministic
15−system where input and output are defined as a series of events
15+system where input and output are defined as a series of events and
16−and effects. The state of Arvo is simply a pure function of its event
16+effects. The state of Arvo is simply a pure function of its event log.
17−log. None of the effects from an event are emitted until the
17+None of the effects from an event are emitted until the event is
18−event is entered in the log and persisted, either to disk or
18+entered in the log and persisted, either to disk or another trusted
19−another trusted source of persistence, such as a Kafka cluster.
19+source of persistence, such as a Kafka cluster. Consequently, Arvo is
20−Consequently, Arvo is a single-level store: everything in its
20+a single-level store: everything in its state is persistent.
23In a more traditional OS, everything in RAM can be erased at any
22In a more traditional OS, everything in RAM can be erased at any
24time by power failure, and is always erased on reboot. Thus, a
23time by power failure, and is always erased on reboot. Thus, a
25primary purpose of a filesystem is to ensure files persist across
24primary purpose of a filesystem is to ensure files persist across
26−power failures and reboots. In Arvo, both power failures and
25+power failures and reboots. In Arvo, both power failures and
27reboots are special cases of suspending computation, which is
26reboots are special cases of suspending computation, which is
28done safely since our event log is already persistent. Therefore,
27done safely since our event log is already persistent. Therefore,
29Clay is not needed in Arvo for persistence. Why, then, do we have a
28Clay is not needed in Arvo for persistence. Why, then, do we have a
@@ -37,7 +36,7 @@ tree. It is easy and intuitive to read from and write to a
37filesystem tree.
36filesystem tree.
39Second, Clay has a distributed revision-control system baked into
38Second, Clay has a distributed revision-control system baked into
40−it. Traditional filesystems are not revision controlled, so
39+it. Traditional filesystems are not revision controlled, so
41userspace software -- such as git -- is written on top of them to
40userspace software -- such as git -- is written on top of them to
42do so. Clay natively provides the same functionality as modern
41do so. Clay natively provides the same functionality as modern
43DVCSes, and more.
42DVCSes, and more.
@@ -47,25 +46,25 @@ it supports typed data and is referentially transparent.
48### Revision Control
47### Revision Control
50−Every urbit has one or more `desk`s, which are independently
49+Every urbit has one or more desks, which are independently
51−revision-controlled branches. Each `desk` contains its own `mark`
50+revision-controlled branches. Each desk contains its own `mark`
52definitions, apps, and so forth.
51definitions, apps, and so forth.
54−Traditionally, an urbit has at least a `%home` `desk` and `%kids` `desk`. The
53+Traditionally, an Urbit ship has at least a `%base` desk, and usually
55−`%home` `desk` has all the system software from the distribution, along with your
54+`%garden` and `%landscape` desks. The `%base` desk has the kernel and
56−personal files. The `%home` `desk` is a fork of the `%kids` desk of whichever ship
55+base system software. The `%garden` desk has software pertaining to
56+the home screen. The `%landscape` desk contains software for the
57+Groups app. The `%base` desk is a fork of the `%base` desk of
57−you download [OTAs](/docs/glossary/ota-updates) from - typically your sponsor,
58+whichever ship you download system updates from - typically your
58−but theoretically may be any ship. You will also find references to a `%base`
59+sponsor, but theoretically may be any ship.
59−`desk` - which is not a real `desk`, rather it just a hash associated to the
60−`desk` from which your `%home` `desk` was forked.
62−A `desk` is a series of numbered commits, the most recent of which
61+A desk is a series of numbered commits, the most recent of which
63−represents the current state of the `desk`. A commit is composed of
62+represents the current state of the desk. A commit is composed of
64(1) an absolute time when it was created, (2) a list of zero or
63(1) an absolute time when it was created, (2) a list of zero or
65more parents, and (3) a map from paths to data.
64more parents, and (3) a map from paths to data.
67Most commits have exactly one parent, but the initial commit on a
66Most commits have exactly one parent, but the initial commit on a
68−`desk` may have zero parents, and merge commits have more than one
67+desk may have zero parents, and merge commits have more than one
71The non-metadata is stored as a `map` of `path`s to data. It's
70The non-metadata is stored as a `map` of `path`s to data. It's
@@ -88,10 +87,10 @@ only on the data within and not on whether or not it's stored
88directly, so we may on occasion rearrange the contents of the
87directly, so we may on occasion rearrange the contents of the
89blob store for performance reasons.
88blob store for performance reasons.
91−Recall that a `desk` is a series of numbered commits. Not every
90+Recall that a desk is a series of numbered commits. Not every
92−commit in a `desk` must be numbered. For example, if the base `desk`
91+commit in a desk must be numbered. For example, if the `%base` desk
93−has had 50 commits since home was forked from it, then a merge
92+has had 50 commits since `%foo` was forked from it, then a merge
94−from base to home will only add a single revision number to home,
93+from `%base` to `%foo` will only add a single revision number to home,
95although the full commit history will be accessible by traversing
94although the full commit history will be accessible by traversing
96the parentage of the individual commits.
95the parentage of the individual commits.
@@ -101,25 +100,25 @@ the topmost commit is always numbered, and every numbered commit
101is an ancestor of every later numbered commit.
100is an ancestor of every later numbered commit.
103There are three ways to refer to particular commits in the
102There are three ways to refer to particular commits in the
104−revision history. Firstly, one can use the revision number.
103+revision history. Firstly, one can use the revision number.
105Secondly, one can use any absolute time between the one numbered
104Secondly, one can use any absolute time between the one numbered
106commit and the next (inclusive of the first, exclusive of the
105commit and the next (inclusive of the first, exclusive of the
107−second). Thirdly, every `desk` has a `map` of labels to revision
106+second). Thirdly, every desk has a `map` of labels to revision
108numbers. These labels may be used to refer to specific commits.
107numbers. These labels may be used to refer to specific commits.
110Additionally, Clay is a global filesystem, so data on other urbits
109Additionally, Clay is a global filesystem, so data on other urbits
111−is easily accessible the same way as data on our local urbit. In
110+is easily accessible the same way as data on our local urbit. In
112−general, the path to a particular revision of a `desk` is
111+general, the path to a particular revision of a desk is
113−`/~urbit-name/desk-name/revision`. Thus, to get `/try/readme/md`
112+`/~urbit-name/desk-name/revision`. Thus, to get `/try/readme/md`
114−from revision 5 of the home `desk` on `~sampel-sipnym`, we refer to
113+from revision 5 of the `%base` desk on `~sampel-sipnym`, we refer to
115−`/~sampel-sipnym/home/5/try/readme/md`. Clay's namespace is thus
114+`/~sampel-sipnym/base/5/try/readme/md`. Clay's namespace is thus
116global and referentially transparent.
115global and referentially transparent.
118### A Typed Filesystem
117### A Typed Filesystem
120Since Clay is a general filesystem for storing data of arbitrary
119Since Clay is a general filesystem for storing data of arbitrary
121types, in order to revision control correctly it needs to be
120types, in order to revision control correctly it needs to be
122−aware of types all the way through. Traditional revision control
121+aware of types all the way through. Traditional revision control
123does an excellent job of handling source code, so for source code
122does an excellent job of handling source code, so for source code
124we act very similar to traditional revision control. The
123we act very similar to traditional revision control. The
125challenge is to handle other data similarly well.
124challenge is to handle other data similarly well.
@@ -145,7 +144,7 @@ branches and merged at will.
145Suppose Alice is tasked with touching up a picture, improving the
144Suppose Alice is tasked with touching up a picture, improving the
146color balance, adjusting the contrast, and so forth, while Bob
145color balance, adjusting the contrast, and so forth, while Bob
147has the job of cropping the picture to fit where it's needed and
146has the job of cropping the picture to fit where it's needed and
148−adding textual overlay. Without type-aware revision control,
147+adding textual overlay. Without type-aware revision control,
149these changes must be made serially, requiring Alice and Bob to
148these changes must be made serially, requiring Alice and Bob to
150explicitly coordinate their efforts. With type-aware revision
149explicitly coordinate their efforts. With type-aware revision
151control, these operations may be performed in parallel, and then
150control, these operations may be performed in parallel, and then
@@ -168,7 +167,7 @@ different sentences may be flagged as a conflict. In general,
168prose should be diffed by sentence, not by line.
167prose should be diffed by sentence, not by line.
170As far as we are aware, Clay is the first generalized,
169As far as we are aware, Clay is the first generalized,
171−type-aware revision control system. We'll go into the workings
170+type-aware revision control system. We'll go into the workings
172of this system in some detail.
171of this system in some detail.
@@ -191,7 +190,7 @@ from the text ones.
192More formally, a `mark` is a core with three [arms](/docs/glossary/arm/): `+grab`,
191More formally, a `mark` is a core with three [arms](/docs/glossary/arm/): `+grab`,
193`+grow`, and `+grad`. In `+grab` is a series of functions to
192`+grow`, and `+grad`. In `+grab` is a series of functions to
194−convert from other `mark`s to the given `mark`. In `+grow` is a
193+convert from other `mark`s to the given `mark`. In `+grow` is a
195series of functions to convert from the given `mark` to other
194series of functions to convert from the given `mark` to other
196`mark`s. In `+grad` is `+diff`, `+pact`, `+join`, and `+mash`, and
195`mark`s. In `+grad` is `+diff`, `+pact`, `+join`, and `+mash`, and
@@ -240,7 +239,7 @@ delegate the revision control responsibilities. Then, before
240running any of those functions, Clay will convert to the other
239running any of those functions, Clay will convert to the other
241`mark`, and convert back afterward. For example, the `%hoon` `mark`
240`mark`, and convert back afterward. For example, the `%hoon` `mark`
242is revision-controlled in the same way as `%txt`, so its `+grad`
241is revision-controlled in the same way as `%txt`, so its `+grad`
243−is simply `++ grad %txt`. Of course, `+txt` must be defined in
242+is simply `++ grad %txt`. Of course, `+txt` must be defined in
244`+grow` and `+grab` as well.
243`+grow` and `+grab` as well.
246Every file in Clay has a `mark`, and that `mark` must have a
245Every file in Clay has a `mark`, and that `mark` must have a
@@ -251,4 +250,3 @@ it.
252Additionally, if a file is to be synced out to Unix, then it must
251Additionally, if a file is to be synced out to Unix, then it must
253have conversion routines to and from the `%mime` `mark`.
252have conversion routines to and from the `%mime` `mark`.