@@ -52,6 +52,77 @@ Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
5252
5353## Runes
5454
55+### $| "bucbar"
56+
57+`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
58+
59+##### Syntax
60+
61+Regular: **2-fixed**
62+
63+##### Discussion
64+
65+`$|` is used for validation of values at a finer level than that of types.
66+Recall that a given value of `type` can be equivalently defined by more than one
67+`spec`. For performance reasons, it may be beneficial to restrict oneself to
68+values of a given type that adhere to an abstract syntax tree specified by some
69+subset of those `spec`s that may be used to define a given type.
70+
71+`$|` takes two arguments: a structure `a` and a gate `b` that produces a `flag`
72+that is used to validate values produced by the mold generated by `a` at
73+runtime. `$|(a b)` is a gate that takes in a noun `x` and first pins the product
74+of clamming `a` with `x`, call this `foo`. Then it calls `b` on `foo`. It
75+asserts that the product of `(b foo)` is `&`, and then produces `foo`. This is
76+equivalent to the following (which is not how `$|` is actually defined but has
77+the same behavior):
78+
79+```hoon
80+|= x=*
81+=/ foo ;;(a x)
82+?> (b foo)
83+foo
84+```
85+
86+For example, the elements of a `set` are treated as being unordered, but the
87+values will necessarily possess an order by where they are in the memory. Thus
88+if every `set` is stored using the same order scheme then faster algorithms
89+involving `set`s may be written. Furthermore, if you just place elements in the
90+`set` randomly, it may be mistreated by algorithms already in place that are
91+expecting a certain order. This is not the same thing as casting - it is forcing
92+a type to have a more specific set of values than its mold would suggest. This
93+rune should rarely be used, but it is extremely important when it is.
94+
95+##### Examples
96+
97+```
98+~zod:dojo> =foo $| (list @)
99+ |=(a=(list) (lth (lent a) 4))
100+```
101+This creates a structure `foo` whose values are `list`s with length less than 4.
102+```
103+> (foo ~[1 2 3])
104+~[1 2 3]
105+> (foo ~[1 2 3 4])
106+ford: %ride failed to execute:
107+```
108+
109+
110+The definition of `+set` in `hoon.hoon` is the following:
111+```hoon
112+++ set
113+ |$ [item] :: set
114+ $| (tree item)
115+ |=(a=(tree) ~(apt in a))
116+```
117+Here [`|$`](@/docs/reference/hoon-expressions/rune/bar.md#barbuc) is used to
118+define a mold builder that takes in a mold (given the face `item`) and creates a
119+structure consisting of a `tree` of `item`s with `$|` that is validated with the
120+gate `|=(a=(tree) ~(apt in a))`. `in` is a door in `hoon.hoon` with functions
121+for handling `set`s, and `apt` is an arm in that door that checks that the
122+values in the `tree` are arranged in the particular way that `set`s are arranged
123+in Hoon, namely 'ascending `+mug` hash order'.
124+
125+
55126### `$_` "buccab"
56127
57128`[%bscb p=hoon]`: structure that normalizes to an example.