Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Clay Data Types

This section will be reference documentation for the data types used by our filesystem.

Internal types

These types are only used inside of Clay. These are only relevant if you're working directly on Clay itself, or trying to understand its inner workings.

$cane

The set of changes between the mergebase and one of the desks being merged.

+$  cane
  $:  new=(map path lobe)
      cal=(map path lobe)
      can=(map path cage)
      old=(map path ~)
  ==

  • new is the set of files in the new desk and not in the mergebase.

  • cal is the set of changes in the new desk from the mergebase except for any that are also in the other new desk.

  • can is the set of changes in the new desk from the mergebase and that are also in the other new desk (potential conflicts).

  • old is the set of files in the mergebase and not in the new desk.

$melt

State for ongoing %fuse merges.

  • con maintains the ordering.

  • sto stores the data needed to merge.

  • bas is the base $beak for the merge.

$dojo

Domestic desk state

This is the all the data that is specific to a particular $desk on a domestic ship.

  • qyx is the set of subscribers to this $desk.

  • dom is the data in the $desk.

  • per is a +map of read permissions by path.

  • pew is a +map of write permissions by path.

  • fiz is the state for ongoing %fuse merges.

$nako

New desk data

Sent to other ships to update them about a particular desk. Includes a map of all new aeons to hashes of their commits, the most recent aeon, and sets of all new commits and data. bar is always empty now because we expect you to request any data you don't have yet.

$raft

Formal state

This is the state of the vane. Anything that must be remembered between calls to Clay is stored in this state.

  • rom: the state for all local desks. It consists of a $duct to Dill and a collection of $desks.

  • hoy: the state for all foreign desks.

  • ran: the global, hash-addressed object store. It has maps of commit hashes to commits and content hashes to content.

  • mon: a collection of Unix mount points. $term is the mount point (relative to th pier) and $beam is a domestic Clay directory.

  • hez: the duct used to sync with Unix.

  • cez: a collection of named aermission groups.

  • tyr: app subscriptions.

  • tur: records whether apps are running and which kernel versions they're compatible with.

  • pud: an update that's waiting on a kernel upgrade.

  • bug: sets Clay's verbosity.

$rand

Unvalidated response to a request.

Like a $rant, but with a page of data rather than a cage of it.

$rede

Generic desk state

This is our knowledge of the state of a desk, either foreign or domestic.

  • lim: the most recent @da for which we're confident we have all the information for. For local $desks, this is always now. For foriegn $desks, this is the last time we got a full update from the foreign ship.

  • ref: the request manager for the desk. For domestic $desks, this is null since we handle requests ourselves. For foreign $desks, this keeps track of all pending foriegn requests plus a cache of the responses to previous requests.

  • qyx: the +set of subscriptions to this desk, with listening $ducts. These subscriptions exist only until they've been filled. For domestic $desks, this is simply qyx:dojo - all subscribers to the $desk. For foreign $desks this is all the subscribers from our ship to the foreign $desk.

  • dom: the data in the $desk.

  • per: a +map of read permissions by path.

  • pew: a +map of write permissions by path.

  • fiz: the state for ongoing %fuse merges.

$rind

Foreign request manager

When we send a request to a foreign ship, we keep track of it in here.

  • nix: request counter.

  • bom: a +map of request numbers to requests.

  • fod: reverse +map of requesters to request numbers.

  • haw: a simple cache of common %sing requests.

$bill

The list of agents that should be automatically started on a desk

$update-state

State of outstanding foreign request

An $update-state is used to represent the status of an outstanding request to a foreign $desk.

  • .duct: the duct along which the request was made.

  • .rave: the request itself.

  • .need: a list of hashes yet to be acquired.

  • .nako: a queue of data yet to be validated.

  • .busy: tracks whether or not the request is currently being fulfilled.

$room

Filesystem per domestic ship

This is the representation of the filesystem of a ship on our pier.

  • hun: the duct we use to send messages to Dill to display notifications of filesystem changes. Only %note %gifts should be produced along this $duct. This is set by the %init $move.

  • dos: the set of $desks on this ship, mapped to their $desk state.

$cach

Cached result of a request

$wove

Stored source and request

$rove

Stored request

Like a $rave but with caches of current versions for %next and %many. Generally used when we store a request in our state somewhere.

$rung

Foreign desk data

This contains the filesystem of a neighbour ship. The keys to this +map are all the $desks we know about on their ship.

External types

These types are defined in lull.hoon, and are used in Clay's external interface.

$aeon

Desk revision number

$beam

Global name

The full path to a file or directory.

$beak

Path prefix

A $beam sans the specific file path.

$cable

/lib, /sur or $mark reference

$care

Clay submodule

This specifies what type of information is requested in a subscription or a scry.

  • %a: build a Hoon file at a $path.

  • %b: build a dynamically typed mark by name (a $dais mark interface core).

  • %c: build a dynamically typed mark conversion gate (a $tube) by "from" and "to" $mark names.

  • %d: returns a (set desk) of the $desks that exist on your ship.

  • %e: builds a statically typed mark by name (a $nave mark interface core).

  • %f: builds a statically typed mark converstion gate.

  • %p: produces the permissions for a directory, returned as a [dict dict].

  • %r: requests the file in the same fashion as %x, but wraps the result in a $vase.

  • %s: has miscellaneous debug endpoints.

  • %t: produces a (list path) of descendent $paths for a directory within a $yaki.

  • %u: produces a ? depending on whether or not the specified file exists. It does not check any of its children.

  • %v: requests the entire $dome for a specified $desk at a particular $aeon. When used on a foreign $desk, this get us up-to-date to the requested version.

  • %w: requests the revision number and date of the specified path, returned as a +cass.

  • %x: requests the file at a specified path at the specified commit, returned as a @. If there is no node at that path or if the node has no contents (that is, if +fil:ankh is null), then this crashes.

  • %y: requests an $arch of the specfied commit at the specified path. It will return the bunt of an $arch if the file or directory is not found.

  • %z: requests a recursive hash of a node and all its children, returned as a @uxI.

See the scry reference for more details.

$case

The $case is a type union of:

  • [%da p=@da]: Any @da datetime.

  • [%tas p=@tas]: Any @tas label.

  • [%ud p=@ud]: Any existing revision number.

  • [%uv p=@uv]: Hashed content of some given version of the node in question.

$cash

$case or $tako

$cass

Cases for revision

This is returned by a %w read.

$clue

Tombstone target

  • %lobe: specific $lobe.

  • %all: all safe tombstone targets.

  • %pick: collect garbage.

  • %norm: set default $norm.

  • %worn: set $norm for a specific commit.

  • %seek: backfill tombstoned commit.

$cone

Domes

$dome

Desk data

A $dome is the state of a $desk and associated data.

  • let is the number of the most recently numbered commit. This is also the total number of numbered commits.

  • hit is a map of numerical IDs to commit hashes. These hashes are mapped into their associated commits in the $rang of the the $raft of Clay. In general, the keys of this map are exactly the numbers from 1 to let, with no gaps. Of course, when there are no numbered commits, let is 0, so hit is null. Additionally, each of the commits is an ancestor of every commit numbered greater than this one. Thus, each is a descendant of every commit numbered less than this one. Since it is true that the date in each commit (t.yaki) is no earlier than that of each of its parents, the numbered commits are totally ordered in the same way by both pedigree and date. If that sounds too complicated to you, don't worry about it. It basically behaves exactly as you would expect.

  • lab is a map of textual labels to numbered commits. Labels must be unique across a desk.

  • tom contains the tombstoning policies for all files in the desk.

  • nor is the default tombstoning policy.

  • mim is a cache of the content in the directories that are mounted to Unix.

  • wic contains commits waiting for future kernel versions.

  • liv says whether agents on the desk are running or suspended.

  • ren records which agents have been forced on or off, differing from the desk's desk.bill manifest.

$crew

Permission group

$dict

Effective permission

$domo

Project state

  • let: current revision number

  • hit: map of revisions to their commit hashes

  • lab: map of labels to their revision numbers

$germ

Merge strategy

See the Strategies section of "Using Clay" for further details of their meaning.

$lobe

File reference

This is a hash of a $page. These are most notably used in lat.rang, where they are associated with the actual $page, and as the values in q.yaki, where $paths are associated with their content hashes in a commit.

$miso

File delta

There are four kinds of changes that may be made to a node in a $desk.

  • %del: deletes the node.

  • %ins: inserts a file given by .p.

  • %dif: currently unimplemented. This may seem strange, so we remark that diffs for individual files are implemented using +diff and +pact in $marks. So for an +ankh, which may include both files and directories, %dif being unimplemented really just means that we do not yet have a formal concept of changes in directory structure.

  • %mut: mutates the file using raw data given by .p.

$misu

Computed delta

  • %del: deletes the node.

  • %ins: inserts file .p.

  • %dif: currently unimplemented.

$mizu

New state

$moar

Normal change range

$moat

Range subscription request

This represents a request for all changes between .from and .to on $path. You will be notified when a change is made to the node referenced by the $path or to any of its children.

$mode

External files

This is used when there's a commit from the host system.

$mood

Single subscription request

This represents a request for data related to the state of the $desk at a particular commit, specfied by $case. The $care specifies what kind of information is desired, and the $path specifies the path we are requesting.

$mool

Requests in desk

This is used in a %mult $rave to specify the next version of multiple files with multiple cares.

$nori

Repository action

This describes a change that we are asking Clay to make to the $desk. There are two kinds of changes that may be made: we can modify files or we can apply a label to a commit.

In the & case, we will apply the given changes. In the | case, we will apply the given label to the commit specified in .q, or the current one if it's null.

$nuri

Repository action

Same as a $nori but a +suba rather than $soba.

$norm

Tombstone policy.

An +axal is a recursive directory structure. For each file, a ? says whether it should be tombstoned or not.

$open

Get prelude

This defines the type of a function for retrieving imported files.

$page

A raw, unvalidated file.

This is just the $page defined in arvo.hoon: a pair of a mark and a noun.

$pour

Ford build with content.

A Ford build key in which the leaf nodes (files and directories) carry the $lobe (content hash).

Legacy. This type is no longer part of Clay's public interface. It survives only inside clay.hoon's state-migration core, where it is used to type pre-existing state during an upgrade. The global Ford cache it belonged to was removed from vane state in 2026.

$rang

Data repository

This is a data repository keyed by hash. Thus, this is where the "real" data is stored, but it is only meaningful if we know the hash of what we're looking for.

hut is a +map from commit hashes ($takos) to commits ($yakis). We often get the hashes from hit.dome, which keys them by numerical ID.

lat is a +map from content hashes ($lobes) to the actual content ($pages). We often get the hashes from a $yaki, which references this +map to get the data. There is no $page in $yaki. They are only accessible through lat.

$rant

Response data

This is the data associated to the response to a request.

  • p.p: specifies the type of data that was requested (and is produced).

  • q.p: gives the specific version reported (since a range of versions may be requested in a subscription).

  • r.p: the $desk.

  • .q: the path to the filesystem node.

  • .r: is the data itself (in the format specified by p.p).

$rave

General subscription request

This represents a subscription request for a $desk.

  • %sing: asks for data at single revision.

  • %next: asks to be notified the next time there’s a change to the specified file.

  • %mult: asks to be notified the next time there's a change to a specified set of files.

  • %many: asks to be notified on every change in a $desk for a range of changes (including into the future).

$real

Resolved permissions

  • mod: whether it's a blacklist or whitelist.

  • who: the ships who are blacklisted/whitelisted. It can have both individual ships as well as $crew (permission groups).

$regs

Permission rules for paths

A map from file/directory paths to permission $rules.

$rein

Forced on/off apps

A $dude:gall is the name of a Gall agent and the ? is whether it's forced on or off. An app is forced when it's started despite not being on the desk.bill manifest or stopped when it is on the manifest.

$riff

Request/desist

This represents a request for data about a particular $desk. If .q contains a $rave, then this opens a subscription to the $desk for that data. If .q is null, then this tells Clay to cancel the subscription along this duct.

$riff-any

Versioned $riff

Currently there's only one version.

$rite

New permissions

  • %r: read permissions.

  • %w: write permissions.

  • %rw: both read and write permissions.

$riot

Response

A $riot is a response to a subscription. If null, the subscription has been completed, and no more responses will be sent. Otherwise, the +rant is the produced data.

$rule

Node permission

  • mod: whether it's a blacklist or whitelist.

  • who: the ships or permission groups on the list.

$rump

Relative path

$saba

Patch plus merge

$soak

Ford result

The actual data in the Ford cache.

Legacy. This type is no longer part of Clay's public interface. It survives only inside clay.hoon's state-migration core, where it is used to type pre-existing state during an upgrade. The global Ford cache it belonged to was removed from vane state in 2026.

$soba

Delta

This describes a +list of changes to make to a $desk. The $paths are $paths to files to be changed, and the corresponding $miso value is a description of the change itself.

$suba

Delta

Same as a $soba but with a $misu rather than $miso.

$tako

Commit reference

This is a hash of a $yaki, a commit. These are most notably used as the keys in hut.rang, where they are associated with the actual $yaki, and as the values in hit.dome, where sequential numerical ids are associated with these.

$toro

General change

+unce

Change part of a list.

This is a single change in a list of elements of type .a. For example, (unce @t) is a single change in lines of text.

  • %&: the next .p lines are unchanged.

  • %|: the lines .p have changed to .q.

+urge

List change

This is a parametrized type for list changes. For example, (urge @t) is a list change for lines of text.

$weft

Kernel version

A single kernel version, such as [%zuse 408]. lal is the component name and num its kelvin. Defined in arvo.hoon.

$waft

Kelvin range

A $waft is the result of reading a sys.kelvin file in a desk. It lists all the $wefts (kernel versions) a desk is compatible with. It may either be a single $weft like [%zuse 408], or a range like:

$whom

Ship or named crew

Either a single ship or a set of ships in a $crew (permission group). This is used for read/write permissions.

$yoki

Commit

Either a $yuki or a $yaki. A $yuki is a proto-commit, a $yaki is a final commit whose data is entirely in the general object store.

$yuki

Proto-commit

A $yuki is a proto-commit: a new, proposed commit that has not yet been finalized. This is in contrast to a $yaki. The main difference is that a $yuki may contain actual data, while a $yaki only contains $lobes (content hashes used as references to data in the general object store).

  • .p: commit references of any parents.

  • .q: a +map from file paths to either $page data or $lobes.

$yaki

Finalized commit

  • .p: a +list of the hashes of the parents of this commit. In most cases, this will be a single commit, but in a merge there may be more parents.

  • .q: is a +map of the $paths on a desk to the content hashes at that location. If you understand what a $lobe and a $page is, then the type signature here tells the whole story.

  • .r: is the hash associated with this commit.

  • .t: is the date at which this commit was made.

$zest

How live

This represents the state of apps on the desk.

  • %dead: suspended.

  • %held: suspended pending compatible system update.

  • %live: running.

rock:tire

App states

  • +zest says whether the desk is running or suspended.

  • wic is the set of kernel versions ($wefts) for which the desk has queued commits awaiting kernel updates.

wave:tire

App state changes

  • %wait: blocked commit by $weft.

  • %warp: unblocked commit by $weft.

  • %zest: desk is now running / suspended / held.

$leak

Ford cache key

This includes all build inputs, including transitive dependencies, recursively.

Legacy. This type is no longer part of Clay's public interface. It survives only inside clay.hoon's state-migration core, where it is used to type pre-existing state during an upgrade. The global Ford cache it belonged to was removed from vane state in 2026.

$flow

Global Ford cache

Refcount includes references from other items in the cache, and from spills in each desk.

This is optimized for minimizing the number of rebuilds, and given that, minimizing the amount of memory used. It is relatively slow to lookup, because generating a cache key can be fairly slow (for files, it requires parsing; for $tubes, it even requires building the marks).

Legacy. This type is no longer part of Clay's public interface. It survives only inside clay.hoon's state-migration core, where it is used to type pre-existing state during an upgrade. The global Ford cache it belonged to was removed from vane state in 2026.

$pile

Preprocessed hoon source file

  • sur: surface imports from /sur (/-).

  • lib: library imports from /lib (/+).

  • raw: imports built hoon file at path (/=).

  • raz: imports built hoon files from directory (/~).

  • maz: imports mark definition from /mar (/%).

  • caz: imports mark converter from /mar (/$).

  • bar: unbuilt file imports, as mark (/*).

  • $hoon: the rest of the hoon file.

$taut

File import from /lib or /sur

$mars

Mark conversion request

From .a to .b.

$tube

Mark conversion gate

A gate that takes a $vase and produces a $vase. This is the type of mark convertion gate returned by %c-care scries and read requests.

PreviousClay Architecture
NextClay Examples

Last updated