Urbit Developers
  • Hoon

    • Overview
    • Cheat Sheet
    • Irregular forms
    • Hoon Errors
    • Hoon Style Guide
    • Basic Types
    • Advanced Types
    • Auras
    • Arvo
    • Standard Library

      • 1a: Basic Arithmetic
      • 1b: Tree Addressing
      • 1c: Molds and Mold-Builders
      • 2a: Unit Logic
      • 2b: List Logic
      • 2c: Bit Arithmetic
      • 2d: Bit Logic
      • 2e: Insecure Hashing
      • 2f: Noun Ordering
      • 2g: Unsigned Powers
      • 2h: Set Logic
      • 2i: Map Logic
      • 2j: Jar and Jug Logic
      • 2k: Queue Logic
      • 2l: Container from Container
      • 2m: Container from Noun
      • 2n: Functional Hacks
      • 2o: Normalizing Containers
      • 2p: Serialization
      • 2q: Molds and Mold-Builders
      • 3a: Modular and Signed Ints
      • 3b: Floating Point
      • 3c: Urbit Time
      • 3d: SHA Hash Family
      • 3e: AES encryption (Removed)
      • 3f: Scrambling
      • 3g: Molds and Mold-Builders
      • 4a: Exotic Bases
      • 4b: Text Processing
      • 4c: Tank Printer
      • 4d: Parsing (Tracing)
      • 4e: Parsing (Combinators)
      • 4f: Parsing (Rule-Builders)
      • 4g: Parsing (Outside Caller)
      • 4h: Parsing (ASCII Glyphs)
      • 4i: Parsing (Useful Idioms)
      • 4j: Parsing (Bases and Base Digits)
      • 4k: Atom Printing
      • 4l: Atom Parsing
      • 4m: Formatting Functions
      • 4n: Virtualization
      • 4o: Molds
      • 5a: Compiler Utilities
      • 5b: Macro Expansion
      • 5c: Compiler Backend & Prettyprinter
      • 5d: Parser
      • 5e: Molds and mold builders
      • 5f: Profiling support
      • Runes

        • Constants (Atoms and Strings)
        • + lus · Arms
        • | bar · Cores
        • $ buc · Structures
        • % cen · Calls
        • : col · Cells
        • . dot · Nock
        • / fas · Imports
        • ^ ket · Casts
        • ; mic · Make
        • ~ sig · Hints
        • = tis · Subject
        • ? wut · Conditionals
        • ! zap · Wild
        • --, == Terminators
        • Limbs and wings

          • Limbs
          • Wings
          • Zuse

            • 2d(1-5): To JSON, Wains
            • 2d(6): From JSON
            • 2d(7): From JSON (unit)
            • 2e(2-3): Print & Parse JSON
            • 2m: Ordered Maps
          • Arvo

            • Overview
            • Ames

              • Overview
              • Cryptography
              • API Reference
              • Scry Reference
              • Data Types
              • Behn

                • Overview
                • API Reference
                • Scry Reference
                • Examples
                • Clay

                  • Overview
                  • Architecture
                  • Using Clay
                  • Data Types
                  • Scry Reference
                  • API Reference
                  • Examples
                  • Marks

                    • Overview
                    • Writing Marks
                    • Using Marks
                    • Examples
                  • Dill

                    • Overview
                    • API Reference
                    • Scry Reference
                    • Data Types
                    • Eyre

                      • Overview
                      • External API Reference
                      • Internal API Reference
                      • Scry Reference
                      • Data Types
                      • Guide
                      • Gall

                        • Overview
                        • API Reference
                        • Data Types
                        • Threads Reference
                        • Iris

                          • Overview
                          • API Reference
                          • Data Types
                          • Example
                          • Jael

                            • Overview
                            • API Reference
                            • Scry Reference
                            • Data Types
                            • Examples
                            • Khan

                              • Overview
                              • API Reference
                              • Data Types
                              • Example
                              • Threads

                                • Overview
                                • HTTP API
                                • Reference
                                • Gall

                                  • Start Thread
                                  • Take Result
                                  • Take Facts
                                  • Stop Thread
                                  • Poke Thread
                                  • Examples

                                    • Fetch JSON
                                    • Child Thread
                                    • Main-loop
                                    • Poke Agent
                                    • Scry
                                    • Take Fact
                                  • Concepts

                                    • Scries
                                    • Subscriptions
                                    • Tutorials

                                      • Move Trace
                                      • Reference

                                        • Cryptography
                                        • Filesystem Hierarchy
                                      • Nock

                                        • Nock Definition
                                        • Explanation
                                        • Example
                                        • Implementations
                                        • Vere

                                          • C Runtime System
                                          • Land of Nouns
                                          • API overview by prefix
                                          • C in Urbit
                                          • Writing Jets
                                          • Cryptography
                                          • Azimuth

                                            • Overview
                                            • Urbit HD Wallet
                                            • Azimuth Data Flow
                                            • Azimuth.eth
                                            • Ecliptic.eth
                                            • Advanced Azimuth Tools
                                            • Life and Rift
                                            • Layer 2

                                              • Layer 2 Overview
                                              • Layer 2 Actions
                                              • Transaction Format
                                              • Rollers
                                              • Roller HTTP RPC-API
                                              • Custom Roller Tutorial
                                            • Glossary

                                              • Agent
                                              • Ames
                                              • API
                                              • Aqua
                                              • Arm
                                              • Arvo
                                              • Atom
                                              • Aura
                                              • Aural ASCII
                                              • Azimuth
                                              • Battery
                                              • Behn
                                              • Bowl
                                              • Bridge
                                              • Bunt
                                              • Card
                                              • Case
                                              • Cask
                                              • Cell
                                              • Censures
                                              • Claims
                                              • Clay
                                              • Cold atom
                                              • Comet
                                              • Commit
                                              • Cons
                                              • Context
                                              • Cord
                                              • Core
                                              • Delegated Sending
                                              • Desk
                                              • Dill
                                              • Document Proposal
                                              • Dojo
                                              • Door
                                              • Double-boot
                                              • Dry Gate
                                              • Duct
                                              • Ecliptic
                                              • Entropy
                                              • Event Log
                                              • Eyre
                                              • Face
                                              • Fact
                                              • Foo Bar Baz
                                              • Galaxy
                                              • Gall
                                              • Garden
                                              • Gate
                                              • Generator
                                              • Gift
                                              • Glob
                                              • HD Wallet
                                              • Helm
                                              • Hood
                                              • Hoon
                                              • Invite Tree
                                              • Iris
                                              • Jael
                                              • Jet
                                              • Kelvin versioning
                                              • Kelvin versioning
                                              • Keyfile
                                              • Keywords
                                              • Khan
                                              • Kiln
                                              • Landscape
                                              • Leg
                                              • List
                                              • Loobean
                                              • Lull
                                              • Mark
                                              • Metals
                                              • Mold
                                              • Monad
                                              • Moon
                                              • Move
                                              • Nock
                                              • Noun
                                              • ~
                                              • OTA Updates
                                              • Path Prefix
                                              • Path
                                              • @p
                                              • Payload
                                              • Peek
                                              • pH
                                              • Pier
                                              • Pill
                                              • Planet
                                              • Poke
                                              • Proxies
                                              • Replay
                                              • Factory Reset
                                              • Roller
                                              • Naive rollups
                                              • Rune
                                              • Runtime
                                              • Sail
                                              • Sample
                                              • Scry
                                              • Senate
                                              • Ship
                                              • Slam
                                              • Spider
                                              • Sponsor
                                              • Star
                                              • String
                                              • Subject Oriented Programming
                                              • Subject
                                              • Subscription
                                              • Tape
                                              • Thread
                                              • Trap
                                              • Udon
                                              • Upgrade Proposal
                                              • Userspace
                                              • Vane
                                              • Vase
                                              • Vere
                                              • Voting
                                              • Warm atom
                                              • Wet Gate
                                              • Wing
                                              • Wire
                                              • Wrapper
                                              • ~zod
                                              • Zuse
                                              • Additional

                                                • Cryptography
                                                • Mips (Maps of Maps)
                                                • Software Distribution

                                                  • Overview
                                                  • Docket File
                                                  • Glob
                                                Urbit Developers
                                                • Hoon

                                                  • Overview
                                                  • Cheat Sheet
                                                  • Irregular forms
                                                  • Hoon Errors
                                                  • Hoon Style Guide
                                                  • Basic Types
                                                  • Advanced Types
                                                  • Auras
                                                  • Arvo
                                                  • Standard Library

                                                    • 1a: Basic Arithmetic
                                                    • 1b: Tree Addressing
                                                    • 1c: Molds and Mold-Builders
                                                    • 2a: Unit Logic
                                                    • 2b: List Logic
                                                    • 2c: Bit Arithmetic
                                                    • 2d: Bit Logic
                                                    • 2e: Insecure Hashing
                                                    • 2f: Noun Ordering
                                                    • 2g: Unsigned Powers
                                                    • 2h: Set Logic
                                                    • 2i: Map Logic
                                                    • 2j: Jar and Jug Logic
                                                    • 2k: Queue Logic
                                                    • 2l: Container from Container
                                                    • 2m: Container from Noun
                                                    • 2n: Functional Hacks
                                                    • 2o: Normalizing Containers
                                                    • 2p: Serialization
                                                    • 2q: Molds and Mold-Builders
                                                    • 3a: Modular and Signed Ints
                                                    • 3b: Floating Point
                                                    • 3c: Urbit Time
                                                    • 3d: SHA Hash Family
                                                    • 3e: AES encryption (Removed)
                                                    • 3f: Scrambling
                                                    • 3g: Molds and Mold-Builders
                                                    • 4a: Exotic Bases
                                                    • 4b: Text Processing
                                                    • 4c: Tank Printer
                                                    • 4d: Parsing (Tracing)
                                                    • 4e: Parsing (Combinators)
                                                    • 4f: Parsing (Rule-Builders)
                                                    • 4g: Parsing (Outside Caller)
                                                    • 4h: Parsing (ASCII Glyphs)
                                                    • 4i: Parsing (Useful Idioms)
                                                    • 4j: Parsing (Bases and Base Digits)
                                                    • 4k: Atom Printing
                                                    • 4l: Atom Parsing
                                                    • 4m: Formatting Functions
                                                    • 4n: Virtualization
                                                    • 4o: Molds
                                                    • 5a: Compiler Utilities
                                                    • 5b: Macro Expansion
                                                    • 5c: Compiler Backend & Prettyprinter
                                                    • 5d: Parser
                                                    • 5e: Molds and mold builders
                                                    • 5f: Profiling support
                                                    • Runes

                                                      • Constants (Atoms and Strings)
                                                      • + lus · Arms
                                                      • | bar · Cores
                                                      • $ buc · Structures
                                                      • % cen · Calls
                                                      • : col · Cells
                                                      • . dot · Nock
                                                      • / fas · Imports
                                                      • ^ ket · Casts
                                                      • ; mic · Make
                                                      • ~ sig · Hints
                                                      • = tis · Subject
                                                      • ? wut · Conditionals
                                                      • ! zap · Wild
                                                      • --, == Terminators
                                                      • Limbs and wings

                                                        • Limbs
                                                        • Wings
                                                        • Zuse

                                                          • 2d(1-5): To JSON, Wains
                                                          • 2d(6): From JSON
                                                          • 2d(7): From JSON (unit)
                                                          • 2e(2-3): Print & Parse JSON
                                                          • 2m: Ordered Maps
                                                        • Arvo

                                                          • Overview
                                                          • Ames

                                                            • Overview
                                                            • Cryptography
                                                            • API Reference
                                                            • Scry Reference
                                                            • Data Types
                                                            • Behn

                                                              • Overview
                                                              • API Reference
                                                              • Scry Reference
                                                              • Examples
                                                              • Clay

                                                                • Overview
                                                                • Architecture
                                                                • Using Clay
                                                                • Data Types
                                                                • Scry Reference
                                                                • API Reference
                                                                • Examples
                                                                • Marks

                                                                  • Overview
                                                                  • Writing Marks
                                                                  • Using Marks
                                                                  • Examples
                                                                • Dill

                                                                  • Overview
                                                                  • API Reference
                                                                  • Scry Reference
                                                                  • Data Types
                                                                  • Eyre

                                                                    • Overview
                                                                    • External API Reference
                                                                    • Internal API Reference
                                                                    • Scry Reference
                                                                    • Data Types
                                                                    • Guide
                                                                    • Gall

                                                                      • Overview
                                                                      • API Reference
                                                                      • Data Types
                                                                      • Threads Reference
                                                                      • Iris

                                                                        • Overview
                                                                        • API Reference
                                                                        • Data Types
                                                                        • Example
                                                                        • Jael

                                                                          • Overview
                                                                          • API Reference
                                                                          • Scry Reference
                                                                          • Data Types
                                                                          • Examples
                                                                          • Khan

                                                                            • Overview
                                                                            • API Reference
                                                                            • Data Types
                                                                            • Example
                                                                            • Threads

                                                                              • Overview
                                                                              • HTTP API
                                                                              • Reference
                                                                              • Gall

                                                                                • Start Thread
                                                                                • Take Result
                                                                                • Take Facts
                                                                                • Stop Thread
                                                                                • Poke Thread
                                                                                • Examples

                                                                                  • Fetch JSON
                                                                                  • Child Thread
                                                                                  • Main-loop
                                                                                  • Poke Agent
                                                                                  • Scry
                                                                                  • Take Fact
                                                                                • Concepts

                                                                                  • Scries
                                                                                  • Subscriptions
                                                                                  • Tutorials

                                                                                    • Move Trace
                                                                                    • Reference

                                                                                      • Cryptography
                                                                                      • Filesystem Hierarchy
                                                                                    • Nock

                                                                                      • Nock Definition
                                                                                      • Explanation
                                                                                      • Example
                                                                                      • Implementations
                                                                                      • Vere

                                                                                        • C Runtime System
                                                                                        • Land of Nouns
                                                                                        • API overview by prefix
                                                                                        • C in Urbit
                                                                                        • Writing Jets
                                                                                        • Cryptography
                                                                                        • Azimuth

                                                                                          • Overview
                                                                                          • Urbit HD Wallet
                                                                                          • Azimuth Data Flow
                                                                                          • Azimuth.eth
                                                                                          • Ecliptic.eth
                                                                                          • Advanced Azimuth Tools
                                                                                          • Life and Rift
                                                                                          • Layer 2

                                                                                            • Layer 2 Overview
                                                                                            • Layer 2 Actions
                                                                                            • Transaction Format
                                                                                            • Rollers
                                                                                            • Roller HTTP RPC-API
                                                                                            • Custom Roller Tutorial
                                                                                          • Glossary

                                                                                            • Agent
                                                                                            • Ames
                                                                                            • API
                                                                                            • Aqua
                                                                                            • Arm
                                                                                            • Arvo
                                                                                            • Atom
                                                                                            • Aura
                                                                                            • Aural ASCII
                                                                                            • Azimuth
                                                                                            • Battery
                                                                                            • Behn
                                                                                            • Bowl
                                                                                            • Bridge
                                                                                            • Bunt
                                                                                            • Card
                                                                                            • Case
                                                                                            • Cask
                                                                                            • Cell
                                                                                            • Censures
                                                                                            • Claims
                                                                                            • Clay
                                                                                            • Cold atom
                                                                                            • Comet
                                                                                            • Commit
                                                                                            • Cons
                                                                                            • Context
                                                                                            • Cord
                                                                                            • Core
                                                                                            • Delegated Sending
                                                                                            • Desk
                                                                                            • Dill
                                                                                            • Document Proposal
                                                                                            • Dojo
                                                                                            • Door
                                                                                            • Double-boot
                                                                                            • Dry Gate
                                                                                            • Duct
                                                                                            • Ecliptic
                                                                                            • Entropy
                                                                                            • Event Log
                                                                                            • Eyre
                                                                                            • Face
                                                                                            • Fact
                                                                                            • Foo Bar Baz
                                                                                            • Galaxy
                                                                                            • Gall
                                                                                            • Garden
                                                                                            • Gate
                                                                                            • Generator
                                                                                            • Gift
                                                                                            • Glob
                                                                                            • HD Wallet
                                                                                            • Helm
                                                                                            • Hood
                                                                                            • Hoon
                                                                                            • Invite Tree
                                                                                            • Iris
                                                                                            • Jael
                                                                                            • Jet
                                                                                            • Kelvin versioning
                                                                                            • Kelvin versioning
                                                                                            • Keyfile
                                                                                            • Keywords
                                                                                            • Khan
                                                                                            • Kiln
                                                                                            • Landscape
                                                                                            • Leg
                                                                                            • List
                                                                                            • Loobean
                                                                                            • Lull
                                                                                            • Mark
                                                                                            • Metals
                                                                                            • Mold
                                                                                            • Monad
                                                                                            • Moon
                                                                                            • Move
                                                                                            • Nock
                                                                                            • Noun
                                                                                            • ~
                                                                                            • OTA Updates
                                                                                            • Path Prefix
                                                                                            • Path
                                                                                            • @p
                                                                                            • Payload
                                                                                            • Peek
                                                                                            • pH
                                                                                            • Pier
                                                                                            • Pill
                                                                                            • Planet
                                                                                            • Poke
                                                                                            • Proxies
                                                                                            • Replay
                                                                                            • Factory Reset
                                                                                            • Roller
                                                                                            • Naive rollups
                                                                                            • Rune
                                                                                            • Runtime
                                                                                            • Sail
                                                                                            • Sample
                                                                                            • Scry
                                                                                            • Senate
                                                                                            • Ship
                                                                                            • Slam
                                                                                            • Spider
                                                                                            • Sponsor
                                                                                            • Star
                                                                                            • String
                                                                                            • Subject Oriented Programming
                                                                                            • Subject
                                                                                            • Subscription
                                                                                            • Tape
                                                                                            • Thread
                                                                                            • Trap
                                                                                            • Udon
                                                                                            • Upgrade Proposal
                                                                                            • Userspace
                                                                                            • Vane
                                                                                            • Vase
                                                                                            • Vere
                                                                                            • Voting
                                                                                            • Warm atom
                                                                                            • Wet Gate
                                                                                            • Wing
                                                                                            • Wire
                                                                                            • Wrapper
                                                                                            • ~zod
                                                                                            • Zuse
                                                                                            • Additional

                                                                                              • Cryptography
                                                                                              • Mips (Maps of Maps)
                                                                                              • Software Distribution

                                                                                                • Overview
                                                                                                • Docket File
                                                                                                • Glob
                                                                                              Reference/Arvo/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.

                                                                                              $cult

                                                                                              Subscriptions

                                                                                              +$ cult (jug wove duct)

                                                                                              cults keep track of subscribers. $woves are associated to requests, and each wove is mapped to a set of ducts associated to subscribers who should be notified when the request is filled/updated.


                                                                                              $melt

                                                                                              State for ongoing %fuse merges.

                                                                                              +$ melt [bas=beak con=(list [beak germ]) sto=(map beak (unit dome:clay))]
                                                                                              • con maintains the ordering.
                                                                                              • sto stores the data needed to merge.
                                                                                              • bas is the base beak for the merge.

                                                                                              $dojo

                                                                                              Domestic desk state

                                                                                              +$ dojo
                                                                                              $: qyx=cult :: subscribers
                                                                                              dom=dome :: desk state
                                                                                              per=regs :: read perms per path
                                                                                              pew=regs :: write perms per path
                                                                                              fiz=melt :: state for mega merges
                                                                                              ==

                                                                                              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.

                                                                                              $dome

                                                                                              Desk data

                                                                                              +$ dome
                                                                                              $: let=aeon :: top id
                                                                                              hit=(map aeon tako) :: versions by id
                                                                                              lab=(map @tas aeon) :: labels
                                                                                              tom=(map tako norm) :: tomb policies
                                                                                              nor=norm :: default policy
                                                                                              mim=(map path mime) :: mime cache
                                                                                              fod=flue :: ford cache
                                                                                              wic=(map weft yoki) :: commit-in-waiting
                                                                                              liv=zest :: running agents
                                                                                              ren=rein :: force agents on/off
                                                                                              == ::

                                                                                              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.
                                                                                              • fod is the Ford cache, which keeps a cache of the results of builds performed at this desk's current revision, including a full transitive closure of dependencies for each completed build.
                                                                                              • 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.

                                                                                              $flow

                                                                                              Global Ford cache

                                                                                              +$ flow (map leak [refs=@ud =soak])

                                                                                              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).


                                                                                              $flue

                                                                                              Per-desk build cache

                                                                                              +$ flue [spill=(set leak) sprig=(map mist [=leak =soak])]
                                                                                              • spill is the set of "roots" we have into the global ford cache. We add a root for everything referenced directly or indirectly on a desk, then invalidate them on commit only if their dependencies change.
                                                                                              • sprig is a fast-lookup index over the global ford cache. The only goal is to make cache hits fast.

                                                                                              $mist

                                                                                              Ford build without content

                                                                                              +$ mist
                                                                                              $% [%file =path]
                                                                                              [%nave =mark]
                                                                                              [%dais =mark]
                                                                                              [%cast =mars]
                                                                                              [%tube =mars]
                                                                                              [%vale =path]
                                                                                              [%arch =path]
                                                                                              ==

                                                                                              This is used at the index of sprigs in $flues.


                                                                                              $pour

                                                                                              Ford build with content.

                                                                                              +$ pour
                                                                                              $% [%file =path]
                                                                                              [%nave =mark]
                                                                                              [%dais =mark]
                                                                                              [%cast =mars]
                                                                                              [%tube =mars]
                                                                                              :: leafs
                                                                                              ::
                                                                                              [%vale =path =lobe]
                                                                                              [%arch =path =(map path lobe)]
                                                                                              ==

                                                                                              Like a $mist except the leaf nodes (files and directories) contain the $lobe:clay (content hash).


                                                                                              $soak

                                                                                              Ford result

                                                                                              +$ soak
                                                                                              $% [%cage =cage]
                                                                                              [%vase =vase]
                                                                                              [%arch dir=(map @ta vase)]
                                                                                              [%dais =dais]
                                                                                              [%tube =tube]
                                                                                              ==

                                                                                              The actual data in the Ford cache.


                                                                                              $leak

                                                                                              Ford cache key

                                                                                              +$ leak
                                                                                              $~ [*pour ~]
                                                                                              $: =pour
                                                                                              deps=(set leak)
                                                                                              ==

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


                                                                                              $nako

                                                                                              New desk data

                                                                                              +$ nako :: subscription state
                                                                                              $: gar=(map aeon tako) :: new ids
                                                                                              let=aeon :: next id
                                                                                              lar=(set yaki) :: new commits
                                                                                              bar=~ :: new content
                                                                                              == ::

                                                                                              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

                                                                                              +$ raft :: filesystem
                                                                                              $: rom=room :: domestic
                                                                                              hoy=(map ship rung) :: foreign
                                                                                              ran=rang :: hashes
                                                                                              fad=flow :: ford cache
                                                                                              mon=(map term beam) :: mount points
                                                                                              hez=(unit duct) :: sync duct
                                                                                              cez=(map @ta crew) :: permission groups
                                                                                              tyr=(set duct) :: app subs
                                                                                              tur=rock:tire :: last tire
                                                                                              pud=(unit [=desk =yoki]) :: pending update
                                                                                              bug=[veb=@ mas=@] :: verbosity
                                                                                              == ::

                                                                                              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.
                                                                                              • fad: the global build cache. Each desk has its own fast-lookup index over this global cache.
                                                                                              • 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.

                                                                                              +$ rand :: unvalidated rant
                                                                                              $: p=[p=care q=case r=@tas] :: clade release book
                                                                                              q=path :: spur
                                                                                              r=page :: data
                                                                                              == ::

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


                                                                                              $rede

                                                                                              Generic desk state

                                                                                              +$ rede :: universal project
                                                                                              $: lim=@da :: complete to
                                                                                              ref=(unit rind) :: outgoing requests
                                                                                              qyx=cult :: subscribers
                                                                                              dom=dome :: revision state
                                                                                              per=regs :: read perms per path
                                                                                              pew=regs :: write perms per path
                                                                                              fiz=melt :: domestic mega merges
                                                                                              == ::

                                                                                              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

                                                                                              +$ rind :: request manager
                                                                                              $: nix=@ud :: request index
                                                                                              bom=(map @ud update-state) :: outstanding
                                                                                              fod=(map duct @ud) :: current requests
                                                                                              haw=(map mood (unit cage)) :: simple cache
                                                                                              == ::

                                                                                              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

                                                                                              +$ bill (list dude:gall)

                                                                                              $update-state

                                                                                              State of outstanding foreign request

                                                                                              +$ update-state
                                                                                              $: =duct
                                                                                              =rave
                                                                                              need=(list lobe)
                                                                                              nako=(qeu (unit nako))
                                                                                              busy=_|
                                                                                              ==

                                                                                              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

                                                                                              +$ room :: fs per ship
                                                                                              $: hun=duct :: terminal duct
                                                                                              dos=(map desk dojo) :: native desk
                                                                                              == ::

                                                                                              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

                                                                                              +$ cach (unit (unit cage)) :: cached result

                                                                                              $wove

                                                                                              Stored source and request

                                                                                              +$ wove [for=(unit [=ship ver=@ud]) =rove] :: stored source + req

                                                                                              $rove

                                                                                              Stored request

                                                                                              +$ rove :: stored request
                                                                                              $% [%sing =mood] :: single request
                                                                                              [%next =mood aeon=(unit aeon) =cach] :: next version of one
                                                                                              $: %mult :: next version of any
                                                                                              =mool :: original request
                                                                                              aeon=(unit aeon) :: checking for change
                                                                                              old-cach=(map [=care =path] cach) :: old version
                                                                                              new-cach=(map [=care =path] cach) :: new version
                                                                                              == ::
                                                                                              [%many track=? =moat lobes=(map path lobe)] :: change range
                                                                                              == ::

                                                                                              Like a $rave:clay 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

                                                                                              +$ rung
                                                                                              $: rus=(map desk rede) :: neighbor desks
                                                                                              ==

                                                                                              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:clay

                                                                                              Desk revision number

                                                                                              +$ aeon @ud :: version number

                                                                                              $beam:clay

                                                                                              Global name

                                                                                              +$ beam [[p=ship q=desk r=case] s=path] :: global name

                                                                                              The full path to a file or directory.


                                                                                              $beak:clay

                                                                                              Path prefix

                                                                                              +$ beak [p=ship q=desk r=case] :: path prefix

                                                                                              A $beam:clay sans the specific file path.


                                                                                              $cable:clay

                                                                                              /lib, /sur or mark reference

                                                                                              +$ cable :: lib/sur/mark ref
                                                                                              $: face=(unit term) ::
                                                                                              file-path=term ::
                                                                                              == ::

                                                                                              $care:clay

                                                                                              Clay submodule

                                                                                              +$ care :: clay submode
                                                                                              ?(%a %b %c %d %e %f %p %r %s %t %u %v %w %x %y %z) ::

                                                                                              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:clay dict:clay].
                                                                                              • %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:clay.
                                                                                              • %x: requests the file at a specified path at the specified commit, returned as an @. 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:clay

                                                                                              Revision reference

                                                                                              +$ case :: ship desk case spur
                                                                                              $% [%da p=@da] :: date
                                                                                              [%tas p=@tas] :: label
                                                                                              [%ud p=@ud] :: number
                                                                                              == ::

                                                                                              A commit can be referred to in up to three ways:

                                                                                              • %da: commit date
                                                                                              • %tas: label (seldom used currently)
                                                                                              • %ud: sequential revision number

                                                                                              $cash:clay

                                                                                              case or tako

                                                                                              +$ cash :: case or tako
                                                                                              $% [%tako p=tako] ::
                                                                                              case ::
                                                                                              == ::

                                                                                              $cass:clay

                                                                                              Cases for revision

                                                                                              +$ cass [ud=@ud da=@da] :: cases for revision

                                                                                              This is returned by a %w read.


                                                                                              $clue:clay

                                                                                              Tombstone target

                                                                                              +$ clue :: murder weapon
                                                                                              $% [%lobe =lobe] :: specific lobe
                                                                                              [%all ~] :: all safe targets
                                                                                              [%pick ~] :: collect garbage
                                                                                              [%norm =ship =desk =norm] :: set default norm
                                                                                              [%worn =ship =desk =tako =norm] :: set commit norm
                                                                                              [%seek =ship =desk =cash] :: fetch source blobs
                                                                                              == ::

                                                                                              $cone:clay

                                                                                              Domes

                                                                                              +$ cone (map [ship desk] foam) :: domes

                                                                                              $foam:clay

                                                                                              Desk state with additional metadata

                                                                                              +$ foam
                                                                                              $: dome
                                                                                              tom=(map tako norm)
                                                                                              nor=norm
                                                                                              liv=zest
                                                                                              ren=(map dude:gall ?)
                                                                                              ==
                                                                                              • dome: desk state
                                                                                              • tom: specific tombstone policies
                                                                                              • nor: default tombstone policy
                                                                                              • liv: agent activation status
                                                                                              • ren: %rein'd agents (forced on/off)

                                                                                              $crew:clay

                                                                                              Permission group

                                                                                              +$ crew (set ship) :: permissions group

                                                                                              $dict:clay

                                                                                              Effective permission

                                                                                              +$ dict [src=path rul=real] :: effective permission

                                                                                              $dome:clay

                                                                                              +$ dome :: project state
                                                                                              $: let=@ud :: top id
                                                                                              hit=(map @ud tako) :: changes by id
                                                                                              lab=(map @tas @ud) :: labels
                                                                                              == ::
                                                                                              • let: current revision number
                                                                                              • hit: map of revisions to their commit hashes
                                                                                              • lab: map of labels to their revision numbers

                                                                                              $germ:clay

                                                                                              Merge strategy

                                                                                              +$ germ :: merge style
                                                                                              $? %init :: new desk
                                                                                              %fine :: fast forward
                                                                                              %meet :: orthogonal files
                                                                                              %mate :: orthogonal changes
                                                                                              %meld :: force merge
                                                                                              %only-this :: ours with parents
                                                                                              %only-that :: hers with parents
                                                                                              %take-this :: ours unless absent
                                                                                              %take-that :: hers unless absent
                                                                                              %meet-this :: ours if conflict
                                                                                              %meet-that :: hers if conflict
                                                                                              == ::

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


                                                                                              $lobe:clay

                                                                                              File reference

                                                                                              +$ lobe @uvI :: blob ref

                                                                                              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:clay

                                                                                              File delta

                                                                                              +$ miso :: file delta
                                                                                              $% [%del ~] :: delete
                                                                                              [%ins p=cage] :: insert
                                                                                              [%dif p=cage] :: mutate from diff
                                                                                              [%mut p=cage] :: mutate from raw
                                                                                              == ::

                                                                                              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.

                                                                                              $moar:clay

                                                                                              Normal change range

                                                                                              +$ moar [p=@ud q=@ud] :: normal change range

                                                                                              $moat:clay

                                                                                              Range subscription request

                                                                                              +$ moat [from=case to=case =path] :: change range

                                                                                              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:clay

                                                                                              External files

                                                                                              +$ mode (list [path (unit mime)]) :: external files

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


                                                                                              $mood:clay

                                                                                              Single subscription request

                                                                                              +$ mood [=care =case =path] :: request in desk

                                                                                              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.


                                                                                              $nori:clay

                                                                                              Repository action

                                                                                              +$ nori :: repository action
                                                                                              $% [%& p=soba] :: delta
                                                                                              [%| p=@tas q=(unit aeon)] :: label
                                                                                              == ::

                                                                                              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.


                                                                                              $norm:clay

                                                                                              Tombstone policy.

                                                                                              +$ norm (axal ?)

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


                                                                                              $page:clay

                                                                                              A raw, unvalidated file.

                                                                                              +$ page ^page :: export for compat

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


                                                                                              $rang:clay

                                                                                              Data repository

                                                                                              +$ rang :: repository
                                                                                              $: hut=(map tako yaki) :: changes
                                                                                              lat=(map lobe page) :: data
                                                                                              == ::

                                                                                              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:clay. They are only accessible through lat.


                                                                                              $rant:clay

                                                                                              Response data

                                                                                              +$ rant :: response to request
                                                                                              $: p=[p=care q=case r=desk] :: clade release book
                                                                                              q=path :: spur
                                                                                              r=cage :: 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:clay

                                                                                              General subscription request

                                                                                              +$ rave :: general request
                                                                                              $% [%sing =mood] :: single request
                                                                                              [%next =mood] :: await next version
                                                                                              [%mult =mool] :: next version of any
                                                                                              [%many track=? =moat] :: track range
                                                                                              == ::

                                                                                              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:clay

                                                                                              Resolved permissions

                                                                                              +$ real :: resolved permissions
                                                                                              $: mod=?(%black %white) ::
                                                                                              who=(pair (set ship) (map @ta crew)) ::
                                                                                              == ::
                                                                                              • 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:clay

                                                                                              Permission rules for paths

                                                                                              +$ regs (map path rule) :: rules for paths

                                                                                              A map from file/directory paths to permission rules.


                                                                                              $rein:clay

                                                                                              Forced on/off apps

                                                                                              +$ rein (map dude:gall ?) :: extra 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:clay

                                                                                              Request/desist

                                                                                              +$ riff [p=desk q=(unit rave)] :: 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.


                                                                                              $rite:clay

                                                                                              New permissions

                                                                                              +$ rite :: new permissions
                                                                                              $% [%r red=(unit rule)] :: for read
                                                                                              [%w wit=(unit rule)] :: for write
                                                                                              [%rw red=(unit rule) wit=(unit rule)] :: for read and write
                                                                                              == ::
                                                                                              • %r: read permissions.
                                                                                              • %w: write permissions.
                                                                                              • %rw: both read and write permissions.

                                                                                              $riot:clay

                                                                                              Response

                                                                                              +$ riot (unit rant) :: response+complete

                                                                                              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:clay

                                                                                              Node permission

                                                                                              +$ rule [mod=?(%black %white) who=(set whom)] :: node permission
                                                                                              • mod: whether it's a blacklist or whitelist.
                                                                                              • who: the ships or permission groups on the list.

                                                                                              $soba:clay

                                                                                              Delta

                                                                                              +$ soba (list [p=path q=miso]) :: 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.


                                                                                              $tako:clay

                                                                                              Commit reference

                                                                                              +$ tako @uvI :: yaki ref

                                                                                              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.


                                                                                              +unce:clay

                                                                                              Change part of a list.

                                                                                              ++ unce :: change part
                                                                                              |* a=mold ::
                                                                                              $% [%& p=@ud] :: skip[copy]
                                                                                              [%| p=(list a) q=(list a)] :: p -> q[chunk]
                                                                                              == ::

                                                                                              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:clay

                                                                                              List change

                                                                                              ++ urge |*(a=mold (list (unce a))) :: list change

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


                                                                                              $waft:clay

                                                                                              Kelvin range

                                                                                              +$ waft :: kelvin range
                                                                                              $^ [[%1 ~] p=(set weft)] ::
                                                                                              weft ::

                                                                                              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 417], or a range like:

                                                                                              [[%1 ~] (silt zuse+417 zuse+416 ~)]

                                                                                              $whom:clay

                                                                                              Ship or named crew

                                                                                              +$ whom (each ship @ta) :: 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:clay

                                                                                              Commit

                                                                                              +$ yoki (each yuki yaki) :: 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:clay

                                                                                              Proto-commit

                                                                                              +$ yuki :: proto-commit
                                                                                              $: p=(list tako) :: parents
                                                                                              q=(map path (each page lobe)) :: namespace
                                                                                              == ::

                                                                                              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:clay

                                                                                              Finalized commit

                                                                                              +$ yaki :: commit
                                                                                              $: p=(list tako) :: parents
                                                                                              q=(map path lobe) :: namespace
                                                                                              r=tako :: self-reference
                                                                                              t=@da :: date
                                                                                              == ::
                                                                                              • 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:clay

                                                                                              How live

                                                                                              +$ zest $~(%dead ?(%dead %live %held)) :: how live

                                                                                              This represents the state of apps on the desk.

                                                                                              • %dead: suspended.
                                                                                              • %held: suspended pending compatible system update.
                                                                                              • %live: running.

                                                                                              <-

                                                                                              Using Clay

                                                                                              Scry Reference

                                                                                              ->

                                                                                              Edit this page on GitHub

                                                                                              Last modified March 17, 2023