@@ -4,26 +4,25 @@ weight = 2
44template = "doc.html"
55+++
66
7−Clay is the primary filesystem for the [Arvo](/docs/arvo/overview) operating system,
8−which is the [core](/docs/glossary/core/) of an urbit. The architecture of Clay is
9−intrinsically connected with Arvo, but for this section we assume no knowledge of
10−either Arvo or Urbit. We will point out only those features of
11−Arvo that are necessary for an understanding of Clay, and we will
12−do so only when they arise.
7+Clay is the primary filesystem for the [Arvo](/docs/arvo/overview)
8+operating system, which is the [core](/docs/glossary/core/) of an
9+urbit. The architecture of Clay is intrinsically connected with Arvo,
10+but for this section we assume no knowledge of either Arvo or Urbit.
11+We will point out only those features of Arvo that are necessary for
12+an understanding of Clay, and we will do so only when they arise.
1313
1414The first relevant feature of Arvo is that it is a deterministic
15−system where input and output are defined as a series of events
16−and effects. The state of Arvo is simply a pure function of its event
17−log. None of the effects from an event are emitted until the
18−event is entered in the log and persisted, either to disk or
19−another trusted source of persistence, such as a Kafka cluster.
20−Consequently, Arvo is a single-level store: everything in its
21−state is persistent.
15+system where input and output are defined as a series of events and
16+effects. The state of Arvo is simply a pure function of its event log.
17+None of the effects from an event are emitted until the event is
18+entered in the log and persisted, either to disk or another trusted
19+source of persistence, such as a Kafka cluster. Consequently, Arvo is
20+a single-level store: everything in its state is persistent.
2221
2322In a more traditional OS, everything in RAM can be erased at any
2423time by power failure, and is always erased on reboot. Thus, a
2524primary 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
2726reboots are special cases of suspending computation, which is
2827done safely since our event log is already persistent. Therefore,
2928Clay 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
3736filesystem tree.
3837
3938Second, 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
4140userspace software -- such as git -- is written on top of them to
4241do so. Clay natively provides the same functionality as modern
4342DVCSes, and more.
@@ -47,25 +46,25 @@ it supports typed data and is referentially transparent.
4746
4847### Revision Control
4948
50−Every urbit has one or more `desk`s, which are independently
51−revision-controlled branches. Each `desk` contains its own `mark`
49+Every urbit has one or more desks, which are independently
50+revision-controlled branches. Each desk contains its own `mark`
5251definitions, apps, and so forth.
5352
54−Traditionally, an urbit has at least a `%home` `desk` and `%kids` `desk`. The
55−`%home` `desk` has all the system software from the distribution, along with your
56−personal files. The `%home` `desk` is a fork of the `%kids` desk of whichever ship
57−you download [OTAs](/docs/glossary/ota-updates) from - typically your sponsor,
58−but theoretically may be any ship. You will also find references to a `%base`
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.
53+Traditionally, an Urbit ship has at least a `%base` desk, and usually
54+`%garden` and `%landscape` desks. The `%base` desk has the kernel and
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
58+whichever ship you download system updates from - typically your
59+sponsor, but theoretically may be any ship.
6160
62−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
61+A desk is a series of numbered commits, the most recent of which
62+represents the current state of the desk. A commit is composed of
6463(1) an absolute time when it was created, (2) a list of zero or
6564more parents, and (3) a map from paths to data.
6665
6766Most 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
6968parent.
7069
7170The 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
8887directly, so we may on occasion rearrange the contents of the
8988blob store for performance reasons.
9089
91−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`
93−has had 50 commits since home was forked from it, then a merge
94−from base to home will only add a single revision number to home,
90+Recall that a desk is a series of numbered commits. Not every
91+commit in a desk must be numbered. For example, if the `%base` desk
92+has had 50 commits since `%foo` was forked from it, then a merge
93+from `%base` to `%foo` will only add a single revision number to home,
9594although the full commit history will be accessible by traversing
9695the parentage of the individual commits.
9796
@@ -101,25 +100,25 @@ the topmost commit is always numbered, and every numbered commit
101100is an ancestor of every later numbered commit.
102101
103102There 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.
105104Secondly, one can use any absolute time between the one numbered
106105commit 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
108107numbers. These labels may be used to refer to specific commits.
109108
110109Additionally, Clay is a global filesystem, so data on other urbits
111−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
113−`/~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
115−`/~sampel-sipnym/home/5/try/readme/md`. Clay's namespace is thus
110+is easily accessible the same way as data on our local urbit. In
111+general, the path to a particular revision of a desk is
112+`/~urbit-name/desk-name/revision`. Thus, to get `/try/readme/md`
113+from revision 5 of the `%base` desk on `~sampel-sipnym`, we refer to
114+`/~sampel-sipnym/base/5/try/readme/md`. Clay's namespace is thus
116115global and referentially transparent.
117116
118117### A Typed Filesystem
119118
120119Since Clay is a general filesystem for storing data of arbitrary
121120types, 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
123122does an excellent job of handling source code, so for source code
124123we act very similar to traditional revision control. The
125124challenge is to handle other data similarly well.
@@ -145,7 +144,7 @@ branches and merged at will.
145144Suppose Alice is tasked with touching up a picture, improving the
146145color balance, adjusting the contrast, and so forth, while Bob
147146has 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,
149148these changes must be made serially, requiring Alice and Bob to
150149explicitly coordinate their efforts. With type-aware revision
151150control, these operations may be performed in parallel, and then
@@ -168,7 +167,7 @@ different sentences may be flagged as a conflict. In general,
168167prose should be diffed by sentence, not by line.
169168
170169As 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
172171of this system in some detail.
173172
174173### Marks
@@ -191,7 +190,7 @@ from the text ones.
191190
192191More formally, a `mark` is a core with three [arms](/docs/glossary/arm/): `+grab`,
193192`+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
195194series of functions to convert from the given `mark` to other
196195`mark`s. In `+grad` is `+diff`, `+pact`, `+join`, and `+mash`, and
197196`+form`.
@@ -240,7 +239,7 @@ delegate the revision control responsibilities. Then, before
240239running any of those functions, Clay will convert to the other
241240`mark`, and convert back afterward. For example, the `%hoon` `mark`
242241is 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
244243`+grow` and `+grab` as well.
245244
246245Every file in Clay has a `mark`, and that `mark` must have a
@@ -251,4 +250,3 @@ it.
251250
252251Additionally, if a file is to be synced out to Unix, then it must
253252have conversion routines to and from the `%mime` `mark`.
254−