@@ -6,11 +6,15 @@ template = "doc.html"
66insert_anchor_links = "right"
77+++
88
9−
109Let's go through the type definitions of some of the most used types when working with Graph Store.
1110
1211## Post
12+
1313Here's `sur/post.hoon`
14+
15+<details>
16+ <summary> Code Listing (Click to Expand)</summary>
17+
1418```hoon
1519+$ index (list atom)
1620+$ uid [=resource =index]
@@ -41,6 +45,7 @@ Here's `sur/post.hoon`
4145+$ reference
4246 $% [%graph group=resource =uid]
4347 [%group group=resource]
48+ [%app =ship =desk =path]
4449 ==
4550::
4651+$ content
@@ -50,11 +55,12 @@ Here's `sur/post.hoon`
5055 [%code expression=cord output=(list tank)]
5156 [%reference =reference]
5257 ==
53−--
5458```
5559
60+</details>
5661
5762### Index
63+
5864```hoon
5965+$ index (list atom)
6066+$ uid [=resource =index]
@@ -67,6 +73,7 @@ Here's `sur/post.hoon`
6773An index fragment is not an explicitly defined type, but since an index is `(list atom)`, it follows that the type of an index fragment is `atom`. This is what gives the developer the flexibility to use more than just numbers in an index: any type that is representable as an atom can be used in the index.
6874
6975### Hashing (Part 1)
76+
7077```hoon
7178:: +sham (half sha-256) hash of +validated-portion
7279+$ hash @ux
@@ -78,10 +85,12 @@ An index fragment is not an explicitly defined type, but since an index is `(lis
7885These types are used to cryptographically sign a given post, so that the host of some content cannot act as an imposter, and post content impersonating as someone else. `signature` represents a triple of signed message of hash, author, and author's life at time of posting. These can be used to cryptographically attest to a message. The implementation is a form of asymmetric/public-key encryption, where `q` and `r` are data necessary to look up a ship's public key on azimuth, which can be used to verify the validity of the message.
7986
8087### Content Types
88+
8189```hoon
8290+$ reference
8391 $% [%graph group=resource =uid]
8492 [%group group=resource]
93+ [%app =ship =desk =path]
8594 ==
8695::
8796+$ content
@@ -94,7 +103,11 @@ These types are used to cryptographically sign a given post, so that the host of
94103::
95104```
96105
97−`reference` is a type that models a reference to a graph object. Currently, the valid types of references are either a reference to a specific node in a graph, or a specific group.
106+`reference` is a type that models a reference to a graph object.
107+
108+- `%graph` is a reference to a specific node in a given graph identified by its resource
109+- `%group` is a reference to a given resource itself
110+- `%app` is a reference to an application, hosted on `ship`, located at `desk`, with a `path` that the receiving application can use to link to some content (this is just `/` when unused).
98111
99112`content` enumerates all the possible content types that a post can have. The possible content types can be:
100113
@@ -107,6 +120,7 @@ These types are used to cryptographically sign a given post, so that the host of
107120Currently, these are the only content types supported by Graph Store.
108121
109122### Post
123+
110124```hoon
111125+$ post
112126 $: author=ship
@@ -125,6 +139,7 @@ Post is a fundamental type that represents what we normally think of as a post o
125139An `indexed-post` is a post with an associated index fragment that can be used to validate a post's index with an index fragment that is expected at the end of the index list.
126140
127141### Hashing (Part 2)
142+
128143```hoon
129144+$ validated-portion
130145 $: parent-hash=(unit hash)
@@ -137,24 +152,26 @@ An `indexed-post` is a post with an associated index fragment that can be used t
137152
138153The parts of a `post` that are actually hashed to obtain a value of type the earlier type `hash`.
139154
140−
141155## Graph Store
142156
143157Here's `sur/graph-store.hoon`
144158
159+<details>
160+<summary>Code Listing (Click To Expand)</summary>
161+
145162```hoon
146163+$ graph ((mop atom node) gth)
147164+$ marked-graph [p=graph q=(unit mark)]
148165::
149−+$ node [=post children=internal-graph]
166++$ maybe-post (each post hash)
167++$ node [post=maybe-post children=internal-graph]
150168+$ graphs (map resource marked-graph)
151169::
152−+$ tag-queries (jug term resource)
170++$ tag-queries (jug term uid)
153171::
154172+$ update-log ((mop time logged-update) gth)
155173+$ update-logs (map resource update-log)
156174::
157−::
158175+$ internal-graph
159176 $~ [%empty ~]
160177 $% [%graph p=graph]
@@ -166,18 +183,18 @@ Here's `sur/graph-store.hoon`
166183 =tag-queries
167184 =update-logs
168185 archive=graphs
169− validators=(set mark)
186+ ~
170187 ==
171188::
172189+$ update [p=time q=action]
173190::
174191+$ logged-update [p=time q=logged-action]
175−
192+
176193::
177194+$ logged-action
178195 $% [%add-graph =resource =graph mark=(unit mark) overwrite=?]
179196 [%add-nodes =resource nodes=(map index node)]
180− [%remove-nodes =resource indices=(set index)]
197+ [%remove-posts =resource indices=(set index)]
181198 [%add-signatures =uid =signatures]
182199 [%remove-signatures =uid =signatures]
183200 ==
@@ -186,8 +203,8 @@ Here's `sur/graph-store.hoon`
186203 $% logged-action
187204 [%remove-graph =resource]
188205 ::
189− [%add-tag =term =resource]
190− [%remove-tag =term =resource]
206+ [%add-tag =term =uid]
207+ [%remove-tag =term =uid]
191208 ::
192209 [%archive-graph =resource]
193210 [%unarchive-graph =resource]
@@ -199,22 +216,24 @@ Here's `sur/graph-store.hoon`
199216 [%tags tags=(set term)]
200217 [%tag-queries =tag-queries]
201218 ==
202−--
203−+$ permissions
219+::
220++$ permissions
204221 [admin=permission-level writer=permission-level reader=permission-level]
205222::
206223:: $permission-level: levels of permissions in increasing order
207−::
224+::
208225:: %no: May not add/remove node
209226:: %self: May only nodes beneath nodes that were added by
210227:: the same pilot, may remove nodes that the pilot 'owns'
211228:: %yes: May add a node or remove node
212229+$ permission-level
213230 ?(%no %self %yes)
214−::
215231```
216232
233+</details>
234+
217235### Graph, Node, and Related Objects
236+
218237```hoon
219238+$ graph ((mop atom node) gth)
220239+$ marked-graph [p=graph q=(unit mark)]
@@ -238,18 +257,20 @@ Here's `sur/graph-store.hoon`
238257 ==
239258::
240259```
260+
241261A graph is a loosely interconnected set of data which can reference each other and be arbitrarily nested and interconnected. This concept is based off of the mathematical concept of a graph: a collection of nodes, and connections between nodes called edges.
242262
243263`graph` is a `mop`, a map which maintains ordering on its keys based on a sorting function also known as an ordered map. A graph's keys are `atom`s representing a node's index fragment and whose values are `node`s, where entries are sorted by largest valued keys first, using `gth` as the sorting function. This is the fundamental data structure used in Graph Store.
244264
245265Here are some helpful Wikipedia pages for more info on what this data type represents:
246−- [Graph (abstract data type)](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))
266+
267+- [Graph (abstract data type)](<https://en.wikipedia.org/wiki/Graph_(abstract_data_type)>)
247268- [Graph database](https://en.wikipedia.org/wiki/Graph_database#Background)
248−- [Graph (discrete mathematics)](https://en.wikipedia.org/wiki/Graph_(discrete_mathematics))
269+- [Graph (discrete mathematics)](<https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)>)
249270
250271`node` represents a pair of a `post` and all of its children, which is an `internal-graph`.
251272
252−`internal-graph` is a tagged union representing the state that children can be in. Either a `node` has children in the form of a `graph`, or does not have any and is labeled as `%empty`.
273+`internal-graph` is a tagged union representing the state that children can be in. Either a `node` has children in the form of a `graph`, or does not have any and is labeled as `%empty`.
253274
254275`marked-graph` is the pair of a `graph` and an optionally present `mark`, which is used by Graph Store to validate a graph against the provided validator.
255276
@@ -257,8 +278,6 @@ Here are some helpful Wikipedia pages for more info on what this data type repre
257278
258279`network` is the highest level data structure used by Graph Store to represent all the information that the agent is aware of.
259280
260−
261−
262281### Tag Queries
263282
264283```hoon
@@ -268,13 +287,14 @@ Here are some helpful Wikipedia pages for more info on what this data type repre
268287`tag-queries` is a mapping where the keys are `term`s and the values are a `set` of `resource`s (this pattern is called a `jug`). It is a simple tagging system that allows for various ad-hoc collections, similar to filesystem tags being used to sort different files/folders. While the type's name is `tag-queries`, there is no complex querying system as of now. Currently, you can add term/resources pairs into the tag queries, get a list of all terms in tag-queries, and get the whole `jug` out of Graph Store.
269288
270289### Update (Part 1)
290+
271291```hoon
272292+$ update [p=time q=action]
273293::
274294+$ logged-action
275295 $% [%add-graph =resource =graph mark=(unit mark) overwrite=?]
276296 [%add-nodes =resource nodes=(map index node)]
277− [%remove-nodes =resource indices=(set index)]
297+ [%remove-posts =resource indices=(set index)]
278298 [%add-signatures =uid =signatures]
279299 [%remove-signatures =uid =signatures]
280300 ==
@@ -283,8 +303,8 @@ Here are some helpful Wikipedia pages for more info on what this data type repre
283303 $% logged-action
284304 [%remove-graph =resource]
285305 ::
286− [%add-tag =term =resource]
287− [%remove-tag =term =resource]
306+ [%add-tag =term =uid]
307+ [%remove-tag =term =uid]
288308 ::
289309 [%archive-graph =resource]
290310 [%unarchive-graph =resource]
@@ -301,9 +321,10 @@ Here are some helpful Wikipedia pages for more info on what this data type repre
301321
302322The `update` type is what is used to interact with Graph Store. It is used both to update subscribers with data (outgoing data) and to write to Graph Store itself (incoming data). All actions are meant to be sent as pokes to Graph Store in the form of a `action` (encapsulated by a `graph-update`), except for the last three actions ,`%keys`, `%tags`, and `%tag-queries`, which must be sent scry requests. All actions defined here allow you to create/read/update/delete various objects in a running Graph Store gall agent. An `action` encapsulates all `logged-action`; any `logged-action` is an `action`, but not necessarily the other way around.
303323
304−If you want to check out a relevant code listing to see how graph store handles these pokes, check out the `graph-update` arm in the poke handler at [`app/graph-store.hoon`](https://github.com/urbit/urbit/blob/e2ad6e3e9219c8bfad62f27f05c7cac94c9effa8/pkg/arvo/app/graph-store.hoon#L221-L227)
324+<!-- todo link to reference explaining pokes -->
305325
306326### Update (Part 2)
327+
307328```hoon
308329+$ update-log ((mop time logged-update) gth)
309330+$ update-logs (map resource update-log)
@@ -320,6 +341,7 @@ It is important to note that the source of truth is actually the `update-logs`,
320341The reason for having the main CRUD actions being `logged-update`s is so that Graph Store knows which order to process the log entries in when it is rebuilding its current state. The time associated with the `logged-update` is a way of specifying the canonical order to process operations. All other actions that aren't part of logged-update stand on their own and don't need a timestamp in order to properly apply them.
321342
322343### Permissions
344+
323345```hoon
324346+$ permissions
325347 [admin=permission-level writer=permission-level reader=permission-level]
@@ -335,4 +357,3 @@ The reason for having the main CRUD actions being `logged-update`s is so that Gr
335357```
336358
337359These are the types from the permissioning system explained earlier. `permissions` is just a length-3 cell of `permissions-level`s for Admins, Writers, and Readers respectively.
338−