@@ -1,73 +1,73 @@
1−---
2−date: ~2016.10.25
3−type: post
4−title: Toward a new %clay
5−author: Curtis Yarvin
6−preview: Urbit's revision-control system, `%clay`, is itself due for a (medium-sized) revision!
7−layout: urbit,post
8−navmode: navbar
9−navdpad: false
10−navselect: blog
11−navpath: /
12−navhome: /
13−navclass: urbit
14−---
15−<br /> <br />
1++++
2+title = "Toward a New %clay"
3+date = "2016-07-13"
4+description = "Urbit's revision-control system, %clay, is itself due for a (medium-sized) revision!"
5+aliases = [
6+ "/posts/essays/toward-a-new-clay",
7+ "/posts/toward-a-new-clay",
8+ "/blog/clay"
9+]
10+
11+[extra]
12+author = "Curtis Yarvin"
13+ship = "~sorreg-namtyv"
14++++
15+
1616TLDR: (a) Urbit's revision-control system, `%clay`, is itself due
17−for a (medium-sized) revision! (b) this time, you yourself can
18−really help! (c) please don't give away the buried spoiler!
17+for a (medium-sized) revision! (b) this time, you yourself can
18+really help! (c) please don't give away the buried spoiler!
1919
2020This explanation does not (or at least should not) require you to
2121know anything about Urbit.
2222
2323### But %clay is already pretty cool
2424
25−Of course, nothing in Urbit is allowed to be *lame*. `%clay` is
26−actually quite cool. It does need some work. But first, let's
25+Of course, nothing in Urbit is allowed to be _lame_. `%clay` is
26+actually quite cool. It does need some work. But first, let's
2727talk about what it is and why it's cool.
2828
2929`%clay` is the Arvo vane (Urbit kernel module) for revision
30−control. It's an authenticated, human-memorable global immutable
31−namespace which is also a typed revision-control system. It's
32−also very good at subscription and synchronization. Urbit
30+control. It's an authenticated, human-memorable global immutable
31+namespace which is also a typed revision-control system. It's
32+also very good at subscription and synchronization. Urbit
3333currently uses `%clay` to distribute live hotpatches; we
3434transparently upgrade the whole network with one checkin.
3535
3636### Compared to other revision-control systems
3737
38−`%clay` is clearly a vanilla DVCS in the modern `git` style. Of
38+`%clay` is clearly a vanilla DVCS in the modern `git` style. Of
3939deployed DVCS these days, `%clay` is probably closest in spirit
4040to `bzr` or maybe `fossil`.
4141
4242Obviously, as a part of a larger whole, you would expect any
43−Urbit RCS to be brutally spartan. `%clay` is. It's even more
44−spartan than `bzr`.
43+Urbit RCS to be brutally spartan. `%clay` is. It's even more
44+spartan than `bzr`.
4545
46−(In fact, it's really too spartan to fully use at the moment. We
46+(In fact, it's really too spartan to fully use at the moment. We
4747ourselves still use `%clay` mainly as a distribution system, and
48−do all internal development on Github. This is because the
48+do all internal development on GitHub. This is because the
4949present `%clay` lacks a few little conveniences, like commit
50−messages. See upgrades, below.)
50+messages. See upgrades, below.)
5151
52−There are lots of normal DVCS things in `%clay`. But there are
53−also cool and unusual ones. Let's take a brief tour of the
52+There are lots of normal DVCS things in `%clay`. But there are
53+also cool and unusual ones. Let's take a brief tour of the
5454high-level system, then describe what we think should change
5555about it.
5656
5757### Anatomy of a DVCS
5858
59−A DVCS is a historical state graph. A point in this graph is a
59+A DVCS is a historical state graph. A point in this graph is a
6060snapshot of some tree-structured system, like a filesystem.
6161
6262These snapshots, including recursive internal nodes, are stored in
63−a content-addressable store. Pointers in this store are used to
63+a content-addressable store. Pointers in this store are used to
6464construct a revision graph, whose edges are edit and/or merge
65−actions. Some sort of namespace attaches meaningful names to
65+actions. Some sort of namespace attaches meaningful names to
6666current revisions in this graph.
6767
6868There are six big questions in the design of a DVCS:
6969
70−- how are snapshots named?
70+- how are snapshots named?
7171- what is the data structure within a snapshot?
7272- how does it map to the Unix filesystem?
7373- how is the system queried?
@@ -78,16 +78,16 @@ There are six big questions in the design of a DVCS:
7878
7979A good way to summarize `%clay` (at present) is that its answers
8080to the first four questions are interesting, and its answers to
81−the last two are boring. We'll talk about all six, though.
81+the last two are boring. We'll talk about all six, though.
8282
8383### Global namespace: [ship desk case]
8484
85−The permanent global name of a `%clay` snapshot is a `++beak`. A beak
85+The permanent global name of a `%clay` snapshot is a `++beak`. A beak
8686is a triple: `[ship desk case]`.
8787
88−The `++ship` is an Urbit ship. A ship is a network address, a
89−human-memorable name and a cryptographic identity. The address
90−width is variable; shorter addresses are more desirable. Most
88+The `++ship` is an Urbit ship. A ship is a network address, a
89+human-memorable name and a cryptographic identity. The address
90+width is variable; shorter addresses are more desirable. Most
9191users have 32-bit addresses, which we map to four-syllable
9292synthetic names like `~sorreg-namtyv`.
9393
@@ -97,47 +97,47 @@ The `++case` is a version, one of three kinds: a version sequence
9797number, a named label, or a date.
9898
9999In the Urbit path syntax, the beak is the first three segments of
100−the path: `/ship/desk/case/my/cat/picture`.
100+the path: `/ship/desk/case/my/cat/picture`.
101101
102102In most cases, a path parser has a default ship, desk and case,
103−each of which can be replaced by `=`. So `/=home=/my/cat/picture`
103+each of which can be replaced by `=`. So `/=home=/my/cat/picture`
104104is the data at `/my/cat/picture` on your own ship, in the `%home`
105−desk, right now. Immutability doesn't have to be inconvenient.
105+desk, right now. Immutability doesn't have to be inconvenient.
106106
107−`%clay` has no concept of a mutable name or a magic `HEAD`. Use
108−the current date. If you're referring to remote data and you're
107+`%clay` has no concept of a mutable name or a magic `HEAD`. Use
108+the current date. If you're referring to remote data and you're
109109worried about clock skew, subtract a second or three, or be
110−prepared to block. (Or keep your clock unskewed, which shouldn't
111−be *that* hard.) It's not like mutable-name schemes work any
110+prepared to block. (Or keep your clock unskewed, which shouldn't
111+be _that_ hard.) It's not like mutable-name schemes work any
112112better than this anyway.
113113
114−(Immutability is central to `%clay`. `git` merely adopted the
115−reflog. `%clay` was born in it, molded by it...)
114+(Immutability is central to `%clay`. `git` merely adopted the
115+reflog. `%clay` was born in it, molded by it...)
116116
117117`%clay` is objective; each Urbit node hosts only one ship, but
118−treats domestic and foreign data (almost) the same way. If you
118+treats domestic and foreign data (almost) the same way. If you
119119ask your `%clay` repository for someone else's data, it will
120120block the request until it gets the data, which it then caches.
121121At present, we always fulfill requests from the origin ship,
122122though in future we could certainly use it as a tracker.
123123
124124If `%clay` discards cached data, it keeps a hash, so that your
125−urbit can't violate the local illusion of immutability. We
125+urbit can't violate the local illusion of immutability. We
126126can't, of course, prevent anyone else's ship from sending
127−conflicting claims in different directions. But we can prevent
127+conflicting claims in different directions. But we can prevent
128128programs on our own ship from hearing about them, meaning that we
129129retain local referential transparency.
130130
131131### Local structure: dome, arch, leaf and mark
132132
133−A `%clay` snapshot is called a `++dome`. A dome is the `%clay`
134−equivalent of a tree-structured filesystem.
133+A `%clay` snapshot is called a `++dome`. A dome is the `%clay`
134+equivalent of a tree-structured filesystem.
135135
136136Each node in this tree is one uniform structure, an `++arch`,
137−which is both file and directory. A `++leaf` or data value in
137+which is both file and directory. A `++leaf` or data value in
138138this arch is a typed document.
139139
140−A logical document type is called a `++mark`. A mark is a
140+A logical document type is called a `++mark`. A mark is a
141141symbolic pointer to a Hoon source file, in the same dome, for an
142142engine that can validate, compare, and/or convert
143143documents of that mark.
@@ -146,8 +146,8 @@ Let's go over arches and marks a little more closely...
146146
147147#### An arch is a uniform filesystem node
148148
149−Most filesystems and RCS have modal nodes. For instance, a git
150−data node can be a blob or a tree. `%clay` (and the Urbit
149+Most filesystems and RCS have modal nodes. For instance, a git
150+data node can be a blob or a tree. `%clay` (and the Urbit
151151namespace in general) has one kind of node, an `arch`:
152152
153153```
@@ -156,24 +156,24 @@ namespace in general) has one kind of node, an `arch`:
156156```
157157
158158An arch has an optional typed-data leaf, and optional named
159−children. In Unix terms, it's a file, a directory, or both. It
159+children. In Unix terms, it's a file, a directory, or both. It
160160can't be neither: an empty arch, with no data and no children, is
161−auto-pruned. As in `git` (but not in Unix), the hierarchy is a
162−pure function of its leaves. Paths exist only because of the
161+auto-pruned. As in `git` (but not in Unix), the hierarchy is a
162+pure function of its leaves. Paths exist only because of the
163163data they point to.
164164
165165The `++knot` names in an arch path are also a little special.
166166They're typed, in a sense; any knot can be parsed invertibly into
167−a typed atom. The atom is an arbitrary unsigned integer. Its
167+a typed atom. The atom is an arbitrary unsigned integer. Its
168168type (an `++aura` if you know Hoon) defines the semantics and
169169presentation of the atom: for instance, a symbol, a decimal,
170−a date, etc.
170+a date, etc.
171171
172172Ultimately a filesystem is a database, and a path is a primary
173−key. It's very useful to be able to store simple data in this
173+key. It's very useful to be able to store simple data in this
174174key, in a standard and unambiguous way.
175175
176−Why uniform nodes? One, they map nicely to information trees
176+Why uniform nodes? One, they map nicely to information trees
177177where a subtree may need some custom collective presentation,
178178not an automatically generated Apache style directory listing.
179179Two, non-uniform nodes introduce a whole pointless category of
@@ -181,34 +181,34 @@ node type conflicts -- for which life is far too short.
181181
182182#### A mark is an executable document type
183183
184−A mark is "like an executable MIME type." It's best defined as a
184+A mark is "like an executable MIME type." It's best defined as a
185185symbolic mapping from a filesystem to a schema engine.
186186
187187If you have a MIME type `text/html`, you need to watch the
188−Internets to track what the W3C thinks HTML is. If you have an
188+Internets to track what the W3C thinks HTML is. If you have an
189189Urbit mark `%html`, you can functionally construct (using our
190190insanely powerful functional build vane `%ford`) a core which
191191can validate or normalize HTML, apply patch and diff logic, and
192−translate to and from other marks. `%ford` can even reason about
192+translate to and from other marks. `%ford` can even reason about
193193translation paths and construct multistep conversions.
194194
195195(Urbit does not actually have this super-smart `%html` mark right
196−now. But it probably should, huh. And this page was composed in
196+now. But it probably should, huh. And this page was composed in
197197Markdown and translated to HTML by `%ford`.)
198198
199−Where does the source code of a mark live? Within the same dome
200−as the data it describes. `%html` files are described by the
199+Where does the source code of a mark live? Within the same dome
200+as the data it describes. `%html` files are described by the
201201Hoon source at `/===/mar/html`, which perhaps gets mapped into
202202your Unix filesystem at `$ship/home/mar/html.hoon`.
203203
204−This Hoon file is not self-contained. It has dependencies. The
204+This Hoon file is not self-contained. It has dependencies. The
205205`%html` mark may depend on various structures and libraries
206−elsewhere in Urbit. But the source code for all them is within
206+elsewhere in Urbit. But the source code for all them is within
207207this dome.
208208
209−One constraint this puts on domes is that *all domes are
210−descendants of the base system dome*. Domes are versions of one
211−reality, not fragments of that reality. You can't create a new
209+One constraint this puts on domes is that _all domes are
210+descendants of the base system dome_. Domes are versions of one
211+reality, not fragments of that reality. You can't create a new
212212empty dome -- you'd have no mark source, and be unable to install
213213any validated files.
214214
@@ -219,13 +219,13 @@ weird collisions between non-parallel things don't happen.
219219
220220### Unix mapping and mounting
221221
222−Every DVCS is its own filesystem in a sense. But every DVCS
222+Every DVCS is its own filesystem in a sense. But every DVCS
223223works by mapping and mounting itself, in some sense, to Unix.
224224
225225#### Mapping arches to Unix
226226
227−How do we map arches into Unix? The arch structure maps 1:1 to
228−the Unix directory tree. When the arch has a leaf, we derive a
227+How do we map arches into Unix? The arch structure maps 1:1 to
228+the Unix directory tree. When the arch has a leaf, we derive a
229229dot extension from the file's mark.
230230
231231So, supposing we have a leaf `foo` which is an HTML document
@@ -239,59 +239,59 @@ foo/moo.html
239239```
240240
241241This maps invertibly back into `%clay`, and it looks perfectly
242−unremarkable from the Unix side. File completion sometimes gets
242+unremarkable from the Unix side. File completion sometimes gets
243243a little annoying.
244244
245245It would be if nice every possible Unix tree, even every
246246plausible Unix tree, mapped cleanly and completely to a `%clay`
247−dome. There are always horrid exceptions, even in common use --
248−like extensionless Makefiles. The trivial solution is that if
247+dome. There are always horrid exceptions, even in common use --
248+like extensionless Makefiles. The trivial solution is that if
249249`%clay` finds a file mysterious, it won't track it.
250250
251251One often unquestioned assumption in new system software is that
252−compatibility with old content is important. It's nice, but not
253−that important. Most content in a new system is new content.
254−The important compatibility direction is export, not import. So
252+compatibility with old content is important. It's nice, but not
253+that important. Most content in a new system is new content.
254+The important compatibility direction is export, not import. So
255255the new system should subset, not superset, the ancient formats.
256256
257257### Mounting desks to Unix
258258
259−If a `%clay` desk is *mounted*, it has a two-way live sync to
260−the Unix directory of the same name within the pier.
259+If a `%clay` desk is _mounted_, it has a two-way live sync to
260+the Unix directory of the same name within the pier.
261261
262262When files in a mount directory change, `%clay` notices it
263263through `libuv` filesystem watching (ultimately `inotify()` or
264264`FSEvents`), computes diffs, and automatically commits them to
265−the desk. And if `%clay` creates a new version for its own
265+the desk. And if `%clay` creates a new version for its own
266266urbity reasons, it will revise the Unix files.
267267
268268Keeping all mounted files in the same Unix subdirectory makes it
269−easy to move the whole pier in a tarfile. Edits applied while
269+easy to move the whole pier in a tarfile. Edits applied while
270270the `urbit` process isn't running will be detected and applied
271271the next time it starts.
272272
273273In conventional DVCS terms, `%clay` has a 1:1 static mapping from
274−branches to working directories. Why?
274+branches to working directories. Why?
275275
276−Why not? Do we need that "what branches are checked out in what
277−directories" piece of state? Why force the user to worry about
278−which branches are mounted to which directories? Why not just
279−mount them under their own names? Is there some crippling global
276+Why not? Do we need that "what branches are checked out in what
277+directories" piece of state? Why force the user to worry about
278+which branches are mounted to which directories? Why not just
279+mount them under their own names? Is there some crippling global
280280shortage of disk space for source files? Our planet is running
281−out of inodes? Wut?
281+out of inodes? Wut?
282282
283283### Queries, subscriptions and synchronization
284284
285285There are two ways to get data out of `%clay`: dereference the Urbit
286−namespace, or send a request/subscription. Sync is in userspace.
286+namespace, or send a request/subscription. Sync is in userspace.
287287
288288#### Dereferencing the namespace
289289
290−`%clay` is just part of the full Urbit namespace. The full namespace
290+`%clay` is just part of the full Urbit namespace. The full namespace
291291has a two-character prefix which expresses what vane to query
292−(always `%c` for `%clay`). The suffix is a mode flag; `%x` for
292+(always `%c` for `%clay`). The suffix is a mode flag; `%x` for
293293data, `%y` for a list of children, `%z` for the whole arch
294−subtree, `%w` for the version number. (Each vane has its own
294+subtree, `%w` for the version number. (Each vane has its own
295295modes.)
296296
297297For example, the full path to my cat picture is
@@ -300,11 +300,12 @@ For example, the full path to my cat picture is
300300/cx/~sorreg-namtyv/home/[now]/my/cat/picture
301301```
302302
303−(where `now` is the current date).
303+(where `now` is the current date).
304304
305305If the data model is `++image` (hypothetical -- we don't really
306306do image processing in Urbit right now), the normal way to load
307307this data in a Hoon program is
308+
308309```
309310.^(image /cx/~sorreg-namtyv/home/[now]/my/cat/picture)
310311```
@@ -321,15 +322,15 @@ learn it in future, `[~ ~]` if we know we'll never know it, or
321322`[~ ~ value]` if we know it now.
322323
323324In high-level shell programming (`:dojo`), we can make apparently
324−"blocking" requests to `%clay`. What actually happens: when `%clay`
325+"blocking" requests to `%clay`. What actually happens: when `%clay`
325326produces `~`, we stop trying to compute this expression and wait
326−on one or more blocking requests. When we are unblocked, we
327+on one or more blocking requests. When we are unblocked, we
327328recompute again from scratch; the intermediate computation is not
328329saved at all.
329330
330−Urbit doesn't like to block. It likes to save coherent data
331−structures, not incomplete computation contexts. When Urbit
332−pretends to block for you, this is a courtesy service. You
331+Urbit doesn't like to block. It likes to save coherent data
332+structures, not incomplete computation contexts. When Urbit
333+pretends to block for you, this is a courtesy service. You
333334can return the courtesy of not expecting miracles from it.
334335When in doubt, send an actual request.
335336
@@ -340,7 +341,7 @@ namespace, but can (a) read across case (revision) ranges,
340341and (b) filter by subtree.
341342
342343If the revision range in a request stretches into the future, the
343−request becomes a subscription. Urbit messaging always regards a
344+request becomes a subscription. Urbit messaging always regards a
344345single response as a special case of a subscription.
345346
346347Generally, the response stream created by a request starts with
@@ -350,10 +351,10 @@ closed when the request range is complete.
350351
351352#### Userspace synchronization
352353
353−Synchronization per se is done in userspace. In `%clay`, sync just
354+Synchronization per se is done in userspace. In `%clay`, sync just
354355means an application (typically the `%kiln` module in the system
355356app `:hood`) subscribes to a remote desk, and saves its change
356−stream locally. So sync is really an emergent feature of `%clay`.
357+stream locally. So sync is really an emergent feature of `%clay`.
357358
358359### Revision graph
359360
@@ -361,17 +362,17 @@ stream locally. So sync is really an emergent feature of `%clay`.
361362Some changes are proposed below, however.
362363
363364As in any DVCS, a dome is the child of one parent dome (an edit)
364−or more parents (a merge). Often the parent of any revision is
365+or more parents (a merge). Often the parent of any revision is
365366the previous version in the sequence, but it can be anything.
366367
367368### Storage model
368369
369−`%clay`'s storage model is completely uninteresting. It's also a
370+`%clay`'s storage model is completely uninteresting. It's also a
370371little funky and I want to change it, so I'll be super vague.
371372
372373A `++lobe`, a 128-bit atom, is the Merkle hash of a `blob`, which
373−is essentially a leaf. All blobs are stored in a hash table
374−(`(map lobe blob)`), and reference each other through lobes.
374+is essentially a leaf. All blobs are stored in a hash table
375+(`(map lobe blob)`), and reference each other through lobes.
375376
376377At present we don't GC this space at all, because we don't
377378actually delete any roots.
@@ -379,55 +380,55 @@ actually delete any roots.
379380A `blob` may be `%direct`, meaning it's defined as the data
380381itself, or `%delta`, defined as a change against another blob.
381382This is motivated by the desire not to store a full snapshot
382−on every file change. But it may be misguided (see changes #0
383+on every file change. But it may be misguided (see changes #0
383384and #1 below).
384385
385386We cache the full arch tree (`++ankh`) of the latest state in
386−each desk. For current queries, this mitigates a lot of the
387−opportunities for slowness that this data model creates. But the
387+each desk. For current queries, this mitigates a lot of the
388+opportunities for slowness that this data model creates. But the
388389disparity between the speed of the current version and the
389390speed previous version is an undesirable glitch in the API.
390391
391392## Our motivation for change
392393
393−We actually have *three* motivations for change...
394+We actually have _three_ motivations for change...
394395
395396### We need to develop on %clay
396397
397398At present, we're still using `git` as a development platform.
398399`%clay` is certainly used, but just for its strength --
399−deployment. This is starving Urbit of essential experience and
400−basically keeping it lame. So, change is necessary.
400+deployment. This is starving Urbit of essential experience and
401+basically keeping it lame. So, change is necessary.
401402
402403### Change must come from the community
403404
404−"Why?" you ask? "Why must change come from the community?" Well,
405−one, duh. Change always comes from the community.
405+"Why?" you ask? "Why must change come from the community?" Well,
406+one, duh. Change always comes from the community.
406407
407−But two, a great force for change has departed. Philip Monk,
408+But two, a great force for change has departed. Philip Monk,
408409late maintainer of `%clay` (`~wictuc-folrex` in the old era,
409−`~wicdev-wisryt` in the new), is tired of types and typing. He
410+`~wicdev-wisryt` in the new), is tired of types and typing. He
410411spent September roaming with the bison in Montana, and is now
411−literally on his way to Patagonia. On the one hand, Phil still
412+literally on his way to Patagonia. On the one hand, Phil still
412413exists and is not at all unwilling to answer questions, even dumb
413−questions. On the other hand, *Patagonia*.
414+questions. On the other hand, _Patagonia_.
414415
415−So %clay needs a new owner, or owners. At this point, we think
416+So %clay needs a new owner, or owners. At this point, we think
416417the community might be indoctrinated enough to take a stab.
417418
418419Alas, `%clay` already has a pretty checkered ownership history.
419420Long ago I built a `%clay` that was really the only serious
420−design failure in Arvo. Then Jared Hance, a brilliant summer
421+design failure in Arvo. Then Jared Hance, a brilliant summer
421422intern, took my broken `%clay` and reformed it into a minimal `git`
422−in about a week. Then Philip modified Jared's `%clay` to be a
423−*typed* revision-control system, which is a pretty cool thing.
423+in about a week. Then Philip modified Jared's `%clay` to be a
424+_typed_ revision-control system, which is a pretty cool thing.
424425
425426But... in none of these transitions did `%clay` actually get
426−*rewritten* per se. While it's a reasonably good vane, it
427+_rewritten_ per se. While it's a reasonably good vane, it
427428does contain one or two historical decisions.
428429
429430We know a lot more about Arvo than we used to, and I think we can
430−revisit many of these decisions. The point of this post is to
431+revisit many of these decisions. The point of this post is to
431432start a `%clay` design discussion that will evolve into actual
432433collective action.
433434
@@ -437,41 +438,41 @@ We're planning a rewards program for contributions to `%clay`.
437438It'll simply involve setting a time period and a pool of real
438439estate, and allocating the pool by judged contribution.
439440
440−This is an experimental program. We'll say more about it later.
441−It may not even happen. It may happen very differently. When in
441+This is an experimental program. We'll say more about it later.
442+It may not even happen. It may happen very differently. When in
442443doubt, don't talk about Fight Club.
443444
444445## Some openings for change
445446
446−Change, of course, must come from the community. No one can
447−dictate change from the top down. We *know* this. But...
447+Change, of course, must come from the community. No one can
448+dictate change from the top down. We _know_ this. But...
448449
449450This list of suggested changes for the next `%clay` is not in any
450−sort of order: priority, structure, difficulty, etc. Let's talk
451−about the changes first; make actual plans second. The numbers
451+sort of order: priority, structure, difficulty, etc. Let's talk
452+about the changes first; make actual plans second. The numbers
452453here are just for convenience.
453454
454−**All changes in this program will happen on the next-generation
455−(`cc-release`) branch.**
455+_All changes in this program will happen on the next-generation
456+(`cc-release`) branch._
456457
457458### Change #0: state reform
458459
459460As mentioned above, the storage model in `%clay`, as the code is
460−at present, feels a little funky to me. There's nothing terribly
461+at present, feels a little funky to me. There's nothing terribly
461462awful about it, but it doesn't feel quite right and its scaling
462463properties are very questionable.
463464
464465Briefly, `%clay` today actually derives the hierarchy from its
465−leaves -- rather than *logically* so deriving it. Only leaves
466−are in the object store. This is just weird, and you can feel
467−`%clay` trying to be something other than what it is. (I blame
466+leaves -- rather than _logically_ so deriving it. Only leaves
467+are in the object store. This is just weird, and you can feel
468+`%clay` trying to be something other than what it is. (I blame
468469Jared, though it's actually my fault.)
469470
470471To store a dome snapshot (`++yaki`), the present code keeps a
471−`(map path blob)` at the root of the dome. This is enough to
472+`(map path blob)` at the root of the dome. This is enough to
472473reconstruct the `++arch` structures the namespace exports.
473474However, all kinds of basic arch operations, like basically `ls`,
474−become `O(n)` in the number of leaves in the dome. This is
475+become `O(n)` in the number of leaves in the dome. This is
475476obviously not quite right.
476477
477478I believe the storage structure should be (removing everything
@@ -492,46 +493,46 @@ Here a `++root` is the universal node, with children addressed by
492493hash, but logically representing the abstract `++arch`.
493494
494495Users of hierarchical filesystems basically expect performance
495−qualities that match the filesystem structure. A huge directory
496−in one place shouldn't affect search speeds somewhere else. And
496+qualities that match the filesystem structure. A huge directory
497+in one place shouldn't affect search speeds somewhere else. And
497498of course, `ls` can't be O(n) in the size of the filesystem.
498499
499500### Change #1: store edges, cache snapshots
500501
501−The current `%clay` is snapshot-oriented, like `git`. The actual
502−changes are discarded. I think this is a bad choice.
502+The current `%clay` is snapshot-oriented, like `git`. The actual
503+changes are discarded. I think this is a bad choice.
503504
504505`%clay` is not a research project, and has no idea of going as
505−far as `darcs` in the "set-of-patches" direction. However, at
506−present we actually throw away the patch (`++nori`).
506+far as `darcs` in the "set-of-patches" direction. However, at
507+present we actually throw away the patch (`++nori`).
507508
508509I think the right DVCS design for `%clay` is a snapshot-oriented
509−system which also keeps the patches. The revision graph has the
510−same general shape as in the old `git` style. But rather than
510+system which also keeps the patches. The revision graph has the
511+same general shape as in the old `git` style. But rather than
511512just deriving the diffs from the snapshots, we can also derive
512−the snapshots from the diffs. When in doubt, we save space by
513+the snapshots from the diffs. When in doubt, we save space by
513514dropping the snapshot, not the diff.
514515
515516For an RCS which is also a general-purpose typed filesystem, it's
516517clear that considering edges (deltas, diffs, changes, etc) as the
517−primary state is optimal. You can use diff functions to derive
518+primary state is optimal. You can use diff functions to derive
518519deltas from snapshots, but in many data models this will always
519−risk losing information from the original action. When in
520+risk losing information from the original action. When in
520521doubt, save what the user did.
521522
522523This is even more true for operations on the tree structure, not
523−on individual leaves. Consider the heuristic energy that `git` has
524+on individual leaves. Consider the heuristic energy that `git` has
524525to go through to figure out when `mv` has been used -- even when
525−`git mv` has been used! (According to the `git` faq, this is
526+`git mv` has been used! (According to the `git` faq, this is
526527because the lowest common denominator remains Linus' style of
527528working with emailed patches.)
528529
529−Edges probably don't even need to be deduplicated. They also can
530+Edges probably don't even need to be deduplicated. They also can
530531contain metadata such as commit messages (which `%clay` has no
531532place for at present).
532533
533534Once edges are recognized as unreclaimed primary state, snapshots
534−can always be derived from the edges. So we can reclaim memory
535+can always be derived from the edges. So we can reclaim memory
535536being used for snapshots.
536537
537538It's also straightforward to have a kind of edge which is a list
@@ -539,27 +540,27 @@ of edges, letting us collapse feature branches trivially.
539540
540541Finally, I think references in edges should wherever possible
541542indirect through the namespace, rather than directly to the
542−content address. The user has strictly more information if you
543+content address. The user has strictly more information if you
543544say you merged `/~sorreg-namtyv/base/987/`, than if all you have
544545is the hash that this reference refers to.
545546
546547### Change #2: unconfuse merge and rebase
547548
548549The dispute between merge and rebase has all the bad smells of
549−a historical wart. But here I'm just not sure what's right.
550+a historical wart. But here I'm just not sure what's right.
550551
551−The user has one *intent* whether merging or rebasing, which is
552−to combine changes on one desk into another. The *algorithm*
552+The user has one _intent_ whether merging or rebasing, which is
553+to combine changes on one desk into another. The _algorithm_
553554used to construct this change, whether operational transformation
554555(rebasing) or a 3-way diff (merging) has one goal: use all
555556available information to model the authors' editing intent as
556−realistically as possible. If we save edges, we should use
557+realistically as possible. If we save edges, we should use
557558edges.
558559
559560Whether to define the resulting change graph with the typical
560561structure of a merge, or the typical structure of a rebase,
561562strikes me as quite arbitrary, and well into the land of "pick
562−one and force everyone to stick with it." But this call demands
563+one and force everyone to stick with it." But this call demands
563564a real expert on RCS workflow, which I'm not.
564565
565566Since `%clay` is a humble part of a larger system and needs to
@@ -569,23 +570,23 @@ different preferences" is not usually the right answer.
569570### Change #3: comment jihad
570571
571572`%clay` needs to be brought up to the documentation standards of
572−`%jael`. This means (a) the formatting matches; (b) the comments
573+`%jael`. This means (a) the formatting matches; (b) the comments
573574are at the same level of quality and ubiquity.
574575
575576The basic commenting standards are: (a) every core (class) needs
576577a block comment explanation; (b) every gate (function) needs a
577578line comment; (c) every face (variable) needs a line comment.
578579
579−This is obviously not just a clerical task. To write these
580−comments, you need to actually understand the code. This is a
580+This is obviously not just a clerical task. To write these
581+comments, you need to actually understand the code. This is a
581582nontrivial but extremely rewarding task, even if the code you're
582−commenting will get replaced.
583+commenting will get replaced.
583584
584−Also, the *symbols* in `%clay` must be brought up to `%jael`
585−quality. There is still far too much four-letterism here.
585+Also, the _symbols_ in `%clay` must be brought up to `%jael`
586+quality. There is still far too much four-letterism here.
586587
587588NB: `%clay` is about 3000 lines of pretty clean Hoon, which is
588−certainly not at all undocumented. We're not exactly looking at
589+certainly not at all undocumented. We're not exactly looking at
589590a Matterhorn of reverse engineering here.
590591
591592### Change #4: knot to coin internal paths
@@ -596,26 +597,26 @@ ASCII symbol as an atom) must be within the range of the
596597invertible noun printer, `++co`.
597598
598599`++co` maps a described data value, a `++coin`, to an ASCII
599−string which is a valid URL segment and Unix filename. Its
600+string which is a valid URL segment and Unix filename. Its
600601friend `++so` inverts the function, perfectly.
601602
602−Almost every knot is the simplest kind of `coin`, a `dime.` A
603+Almost every knot is the simplest kind of `coin`, a `dime.` A
603604dime is a single atom with a rendering type (`aura` if you know
604−Hoon). Auras include `@tas` for symbolic text, `@ud` for
605−unsigned decimal, `@p` for Urbit ship, etc. `++co` can also
605+Hoon). Auras include `@tas` for symbolic text, `@ud` for
606+unsigned decimal, `@p` for Urbit ship, etc. `++co` can also
606607print arbitrary cells, though less prettily.
607608
608609This feature is cool because it lets us stuff data into names in
609−a precise and predictable way. Usually the names in a namespace
610+a precise and predictable way. Usually the names in a namespace
610611are human-meaningful and human-originated, and are therefore
611−symbolic, but there are exceptions. For example, blogposts may
612+symbolic, but there are exceptions. For example, blogposts may
612613want to be named by date.
613614
614615However, it is slightly retarded for the fundamental state of our
615−arches to store the *rendered* string (`++knot`), not the source
616−data (`++coin`). It leads to all kinds of inefficiencies where
617−we're doing way more parsing than we want to. (Parsing also
618−should be jet-propelled, but is not.) It also makes it way too
616+arches to store the _rendered_ string (`++knot`), not the source
617+data (`++coin`). It leads to all kinds of inefficiencies where
618+we're doing way more parsing than we want to. (Parsing also
619+should be jet-propelled, but is not.) It also makes it way too
619620easy to sneak in bad data and make it `%clay`'s problem.
620621
621622So, logically, we'd be shifting from
@@ -630,7 +631,7 @@ So, logically, we'd be shifting from
630631
631632Also, a vanilla `++map` might not be quite the right data
632633structure at this point -- we probably want a custom sorted tree,
633−which separates auras and imposes a custom order on each. This
634+which separates auras and imposes a custom order on each. This
634635would let us serve simple range queries quite efficiently, so
635636long as they match the standard aura order (eg, alphabetical
636637order for symbols).
@@ -638,23 +639,23 @@ order for symbols).
638639### Change #5: dome semantics by reference
639640
640641While the principle that a dome contains its own mark source is
641−elegant, it's a pain in the ass to implement properly. `%clay`
642+elegant, it's a pain in the ass to implement properly. `%clay`
642643certainly does not do it justice at present.
643644
644645The complexity is in checking every change to see whether it
645646includes a change to the mark source (which is very unlikely),
646647or a dependency of the mark source (slightly less unlikely).
647648And if so, do we have to update all the leaves in the dome?
648−This is also very unlikely. And yet, it happens.
649+This is also very unlikely. And yet, it happens.
649650
650651Instead, we could simply designate, by beak (ship, desk, and
651−case) a dome which contains the canonical mark source. This
652+case) a dome which contains the canonical mark source. This
652653would rarely change -- you could upgrade a desk to a new mark
653654dome, but it would be a manual operation and probably a rare one.
654655
655656The common case would just be that everyone uses the current
656657version of the `%base` desk when a desk is created, and never
657−changes it. In practice, this means not every two-byte edit
658+changes it. In practice, this means not every two-byte edit
658659needs to get involved in detecting and/or applying schema
659660evolution, a welcome simplification.
660661
@@ -666,14 +667,14 @@ design is one mark per message structure, the mark namespace gets
666667overloaded fast.
667668
668669So we added an app hierarchy within the mark namespace, using hep
669−`-` as a divider. The `:talk` app expects messages with the mark
670+`-` as a divider. The `:talk` app expects messages with the mark
670671`talk-message`, whose sources is in `/===/mar/talk/message`.
671672
672673This helps, but it doesn't solve another two problems: trivial
673674nouns and containers.
674675
675676It's retarded to have to add a source file to send a `@ud` or a
676−`*`. An aura (see above under `coin`) should be a trivial mark.
677+`*`. An aura (see above under `coin`) should be a trivial mark.
677678
678679Also, we need to be able to construct standard containers of
679680marks: lists, maps, sets, and tuples (or, as a database person
@@ -685,34 +686,34 @@ Another kind of complex mark that needs to exist: conflict,
685686difference, and invalid marks.
686687
687688Conflict data and difference data are two types of noun that are
688−generated in normal RCS operation. If we have the concept of an
689+generated in normal RCS operation. If we have the concept of an
689690`%html` noun, we also need the concept of an invertible change
690691from one `%html` file to another; a merge conflict between two
691692`%html` files; and even a conflict between two marks.
692693
693694There are two kinds of changes to a dome: manual and automatic.
694695Manual changes are initiated by the user and should crash, unless
695−manually overridden. Automatic changes should not crash, ever,
696−and should not lose data. If they create problems, which they
696+manually overridden. Automatic changes should not crash, ever,
697+and should not lose data. If they create problems, which they
697698shouldn't, these problems will need to be cleaned up manually.
698699
699700This is a complex space to navigate, but it requires a conflicted
700701merge to be able to resolve to a valid dome containing conflict
701−leaves, not crash. The present `%clay` goes halfway there and
702+leaves, not crash. The present `%clay` goes halfway there and
702703resolves to a scratch desk, but we can go farther: the whole `git`
703−dumpster-fire of "merge state" deserves destruction. One change
704+dumpster-fire of "merge state" deserves destruction. One change
704705is a merge that produces conflicts, the next is an edit that
705706resolves them.
706707
707−Similarly, all sorts of errors can produce invalid leaves. One
708+Similarly, all sorts of errors can produce invalid leaves. One
708709particularly rare case which is nonetheless important is schema
709710evolution: what happens to files in a mark, when the mark source
710−code changes. They all need to be re-normalized. And this
711−operation can fail, producing an invalid value. (We don't do any
711+code changes. They all need to be re-normalized. And this
712+operation can fail, producing an invalid value. (We don't do any
712713of this now, BTW, although `%ford` has the dependency mechanism to
713−make it possible.) Again, in some cases this should crash the
714+make it possible.) Again, in some cases this should crash the
714715update to the mark source; in other cases, there is no local way
715−to handle the crash.
716+to handle the crash.
716717
717718So there must be a way to preserve invalid nouns that can be
718719repaired by repair tools that expect invalid content, while not
@@ -721,67 +722,67 @@ into using the bad content.
721722
722723The bottom line: a mark needs to be split into two models:
723724`++mark`, the original symbolic mark with its source engine, and
724−something like `++logo`, the meta-mark or mark container. The
725+something like `++logo`, the meta-mark or mark container. The
725726mark is the building block; the logo is the building.
726727
727728### Change #8: filesystem hierarchy standard
728729
729730While all filesystems remain forks of one ur-filesystem, the
730−standard tends to enforce itself. But not define itself.
731+standard tends to enforce itself. But not define itself.
731732
732−I've always hated the current `/mar` for marks, for instance. I
733−prefer `/mac`. But others hate this. And so on. Also, by
733+I've always hated the current `/mar` for marks, for instance. I
734+prefer `/mac`. But others hate this. And so on. Also, by
734735necessity, our nascent "FHS" is heavily biased toward system
735−data, away from user data. This is retarded.
736+data, away from user data. This is retarded.
736737
737−Please focus all bikeshedding energy on this problem! Better to
738+Please focus all bikeshedding energy on this problem! Better to
738739bikeshed about what color to paint the bikeshed, then what shape
739740the bike gears should be.
740741
741742### Change #9: security and access control
742743
743−Oh, yeah, that! They always say not to design security in at the
744−last minute. Unfortunately, this is exactly what we did. There
745−is no security at all in present `%clay`. (There is also no push
744+Oh, yeah, that! They always say not to design security in at the
745+last minute. Unfortunately, this is exactly what we did. There
746+is no security at all in present `%clay`. (There is also no push
746747operation in `%clay`, so it's not as mad as you think -- anyone
747748can read anything, no one can write anything, which is fine in a
748749young network where there are no secrets.)
749750
750751Fortunately, we don't have anything super fancy planned in this
751−area, just basic access-control lists. These obviously need to
752+area, just basic access-control lists. These obviously need to
752753be designed along with the filesystem-hierarchy standard (see
753754elsewhere).
754755
755−Is it even possible to do ACLs properly in `%clay`? At this
756−point, yes. There is an event-oriented security model in Arvo,
756+Is it even possible to do ACLs properly in `%clay`? At this
757+point, yes. There is an event-oriented security model in Arvo,
757758though it isn't really hooked up to anything at the moment.
758−There is also a privilege badge system in `%jael`. The
759+There is also a privilege badge system in `%jael`. The
759760combination of these two features is quite sufficient for a
760761decent ACL model.
761762
762763The idea of event-based security is that every event passed to
763−`%clay` has a security `++mask`. The mask tells us:
764+`%clay` has a security `++mask`. The mask tells us:
764765
765−- the set of ships that has *contaminated* this event
766−- the set of ships that has *endorsed* this event
767−- the set of ships that this event may be *released* to.
766+- the set of ships that has _contaminated_ this event
767+- the set of ships that has _endorsed_ this event
768+- the set of ships that this event may be _released_ to.
768769
769770To simplify this system a little and maybe explain it, the
770−security question in any event is: (a) who has *caused* this
771−event? (b) who may receive its *effects*? (These sets never
771+security question in any event is: (a) who has _caused_ this
772+event? (b) who may receive its _effects_? (These sets never
772773include your urbit itself, of course, only neighbors.)
773774
774775For example, if we're doing something because ship X sent us a
775776packet, and we're going to leak the results of this something
776777back in a response to ship X, once `%clay` knows what our ship
777778thinks of its neighbor X, we should have a good picture of what
778−effects this event should be allowed to cause. If `%jael` knows
779+effects this event should be allowed to cause. If `%jael` knows
779780that X is our friend, `%clay` can know that X can see our cat
780781picture.
781782
782783Causality is separated out into contamination (data from ship X
783784got into the event) and endorsement (ship X signed the whole
784−event). (This may be overdesign.) All these sets can be defined
785+event). (This may be overdesign.) All these sets can be defined
785786as the empty set (eg, releasing to the empty set means no output)
786787or the universal set (input from the universal set could be from
787788anyone, ie, is unauthenticated).
@@ -790,11 +791,11 @@ anyone, ie, is unauthenticated).
790791
791792When you read a leaf from a `%clay` dome, `%clay` is happy to
792793perform any necessary mark conversions (the actual work is done
793−by the `%ford` build vane). You can also just ask for the leaf
794+by the `%ford` build vane). You can also just ask for the leaf
794795in whatever mark `%clay` has it.
795796
796797It's confusing to think of this mark extension as part of the
797−path. You shouldn't say `+cat /===/app/talk/hoon`. You should say
798+path. You shouldn't say `+cat /===/app/talk/hoon`. You should say
798799`+cat /===/app/talk`, or maybe `+cat %hoon /===/app/talk`.
799800
800801A mark-extended namespace may be added to `%ford`, to compensate.
@@ -803,7 +804,7 @@ But type-converting reads are the rare case, not the common case.
803804### Change #11: real queries and indexes
804805
805806A filesystem should postpone being a database until it can no
806−longer do so. So, please don't think about this problem yet.
807+longer do so. So, please don't think about this problem yet.
807808I'm joking, of course!
808809
809810### Change #12: meta-query
@@ -812,36 +813,36 @@ Make it possible to query the list of desks in a ship :-)
812813
813814### Change #13: completely redesign Unix mounting
814815
815−This is actually a series of changes, described below. But
816+This is actually a series of changes, described below. But
816817broadly...
817818
818819One of Urbit's experiments is live two-way synchronization
819820between the Unix filesystem and the revision-control store.
820−Dropbox style, as it were. I think this experiment is basically
821−a failure. It may be right for cat pictures, but I don't think
821+Dropbox style, as it were. I think this experiment is basically
822+a failure. It may be right for cat pictures, but I don't think
822823it's right for Urbit.
823824
824825The fundamental problem is that there are all sorts of weird,
825−flaky ways applications use a mutable filesystem. It's not at
826+flaky ways applications use a mutable filesystem. It's not at
826827all unusual for an editor to change a file by deleting the old
827−file, then writing the new one in its place.
828+file, then writing the new one in its place.
828829
829−You really don't want this to produce a delete change. A simple
830+You really don't want this to produce a delete change. A simple
830831cooldown timer for the sync helps a lot with this, but causes
831−other weirdnesses. In theory, a sync can even cause another
832−change to the same version of the same desk. And so on.
832+other weirdnesses. In theory, a sync can even cause another
833+change to the same version of the same desk. And so on.
833834
834835The thing we fear is just too funky to work (there is some
835−strange "reflux bug" still affecting it) is any sort of *two-way*
836−synchronization between Unix and Urbit.
836+strange "reflux bug" still affecting it) is any sort of _two-way_
837+synchronization between Unix and Urbit.
837838
838839And what I think puts this feature into the deadpool, or at least
839840cold storage, is that there's no useful workflow that actually
840841uses it -- at least, when editing Urbit code.
841842
842843It's actually really nice to have files on a disk that nothing
843−will automatically modify. If you're using `git` and `%clay` in
844−parallel, it's nice to mount your `git` working directory. The
844+will automatically modify. If you're using `git` and `%clay` in
845+parallel, it's nice to mount your `git` working directory. The
845846original Urbit workflow was to work out of a mounted directory,
846847but the two-way updates were just too weird and scary, so now we
847848tend to edit elsewhere and copy in -- which is lame.
@@ -854,25 +855,25 @@ FUSE (in a somewhat experimental state), and filesystem watching
854855
855856The FUSE interface is a good one, though it needs more work.
856857Moreover, it exports the whole Urbit namespace to Unix, not just
857−`%clay`. For reading Urbit data, FUSE is basically ideal.
858+`%clay`. For reading Urbit data, FUSE is basically ideal.
858859
859−The obvious impulse is to make a read-write FUSE. But I don't
860+The obvious impulse is to make a read-write FUSE. But I don't
860861think FUSE should be used for recording changes to an RCS, even
861862though the FUSE API sends you changes as events.
862863
863−There are three reasons for this. One, the actual filesystem
864+There are three reasons for this. One, the actual filesystem
864865writes that Unix apps make are typically of low quality and
865−confusing. Some crack-brained editor will find it completely
866+confusing. Some crack-brained editor will find it completely
866867normal and unremarkable to modify a byte in a file, by deleting
867−the file and rewriting it from scratch. You can use a cooldown
868+the file and rewriting it from scratch. You can use a cooldown
868869timer to wait for this nonsense to converge, but leaving data in
869870heuristic limbo seems like a very bad idea in FUSE-land.
870871
871872The second is that people derive a lot of comfort from seeing
872−actual files on an actual disk. The idea that your datas are
873+actual files on an actual disk. The idea that your datas are
873874stuck in Urbit is slightly terrifying as a user experience.
874−We claim to be reliable. It's actually hard to imagine datas that
875−couldn't be recovered from either snapshot or log. But how can
875+We claim to be reliable. It's actually hard to imagine datas that
876+couldn't be recovered from either snapshot or log. But how can
876877you possibly believe us on this?
877878
878879So I think it's correct to lean all the weight of reading data
@@ -887,35 +888,35 @@ But this is a separate discussion.
887888
888889### Change #15: one-way, nonced working desk
889890
890−A one-way mount is a much less crazy thing. It works the same
891+A one-way mount is a much less crazy thing. It works the same
891892way our two-way mount works today, but with only one writer: the
892893user, via Unix.
893894
894895Since a mount is one-way, it needs to have an absolute write lock
895−on the desk it's writing to. We cannot have a `%home` desk which
896+on the desk it's writing to. We cannot have a `%home` desk which
896897we are also editing with filesystem watching.
897898
898899Instead, we have a temporary and anonymous state that's connected
899−itself with your `%home` desk. Desk names have to be valid
900−symbols, but we can use `hep`, `-`. A reasonable choice is to
900+itself with your `%home` desk. Desk names have to be valid
901+symbols, but we can use `hep`, `-`. A reasonable choice is to
901902pick a random 32-bit name for each mount instance -- so the desk
902−name is not `%home`, but `%home-bosdut-sigder`. (Randomizing
903+name is not `%home`, but `%home-bosdut-sigder`. (Randomizing
903904instead of always using a fixed suffix, say, `%home-work`,
904905just makes all kinds of screwups less likely.)
905906
906907You create a mount simply by mkdiring the desk name in your pier.
907908Just the base name, Urbit will come up with the `%bosdut-sigder`
908−part and put it in a `.desk` file at the desk root. To forget
909−the mount, just delete this file. This avoids the ugly confusion
909+part and put it in a `.desk` file at the desk root. To forget
910+the mount, just delete this file. This avoids the ugly confusion
910911between unmounting a mount, and deleting all the data in it.
911912
912913(Urbit will keep a set of the mount desks it's used and
913−forgotten, not reuse them, and block all requests into them. By
914+forgotten, not reuse them, and block all requests into them. By
914915blocking, we can delete without losing referential transparency.
915916Yes, Virginia, Urbit can forget!)
916917
917918Note that the auto-reload behavior of applications is extremely
918−useful when testing. When testing, you can either switch the
919+useful when testing. When testing, you can either switch the
919920active application desk from `%home` to `%home-bosdut-sigder`,
920921or activate autosync from the latter to the former.
921922
@@ -938,7 +939,7 @@ Otherwise, you're basically, like, reinventing Perforce.
938939
939940More concretely, the Urbit experience today requires `:hood`
940941pokes (Urbit shell commands, basically) for all nontrivial RCS
941−operations, from mounting to merging. Again, there are lots of
942+operations, from mounting to merging. Again, there are lots of
942943situations in which you can write into a mounted filesystem (the
943944protocol for Unix communication could be easily adapted to
944945communicate with a browser-based editor, for instance), but you
@@ -946,22 +947,22 @@ don't want the user to have to bother with an Urbit shell.
946947
947948Even commands like mounting and merging are easily communicated,
948949through filesystem writes that any Unix tool (including many
949−macro editors).
950+macro editors).
950951
951−This is very easy for a filesystem watcher. One such protocol:
952+This is very easy for a filesystem watcher. One such protocol:
952953if you want to send the daemon a command relative to some
953−directory, write a `.ur-command` metafile in that directory. The
954+directory, write a `.ur-command` metafile in that directory. The
954955daemon accepts the command by deleting it.
955956
956957The user experience is that you configure your mounts by simply
957−making the directories and configuring dotfiles in them. Unlike
958+making the directories and configuring dotfiles in them. Unlike
958959in the present system, Urbit will never modify your datas
959960silently in the background.
960961
961962Here's what this looks like:
962963
963−Suppose you want to edit some data in the `%home` desk. Your
964−data is in `/=home=/mar/talk`. You also want a read-only view
964+Suppose you want to edit some data in the `%home` desk. Your
965+data is in `/=home=/mar/talk`. You also want a read-only view
965966of `/=home=/arvo`.
966967
967968From Unix, you do something like this:
@@ -974,18 +975,18 @@ From Unix, you do something like this:
974975 $ touch home/arvo/.read
975976```
976977
977−Want to commit your changes? That means merging the working
978−desk, `%home-bosdut-sigder`, into the `%home`. Put a commit message
979−into `home/.commit` and it'll happen. If there's an error, it
978+Want to commit your changes? That means merging the working
979+desk, `%home-bosdut-sigder`, into the `%home`. Put a commit message
980+into `home/.commit` and it'll happen. If there's an error, it
980981will appear as `.error`.
981982
982983The mount has a .version file which simply contains the change
983−number (of the working desk) which any edits are relative to. If
984+number (of the working desk) which any edits are relative to. If
984985the urbit daemon is running and watching, edits will be absorbed
985986quickly (probably after a heuristic timeout), and the version
986−incremented. But we always are confident that the edits are
987+incremented. But we always are confident that the edits are
987988against the latest version, or at least we can use this as a
988−sanity check. All kinds of insane things can happen to get a
989+sanity check. All kinds of insane things can happen to get a
989990filesystem out of consistency.
990991
991992This design obviously needs a little fleshing out, but I'm quite
@@ -994,12 +995,12 @@ from Unix.
994995
995996## In conclusion
996997
997−There's obviously a lot of fun here! There are two things you
998+There's obviously a lot of fun here! There are two things you
998999can do right now.
9991000
10001001One, talk about `%clay` on [this forum
10011002thread](http://urbit.org/~~/fora/posts/~2016.10.25..17.37.47..6937~/) or
1002−on [:talk](http://urbit.org/stream). Both hosted on Urbit
1003+on [:talk](http://urbit.org/stream). Both hosted on Urbit
10031004itself!
10041005
10051006Two, poke around the