@@ -47,54 +47,194 @@ Graph Store can be poked with a `graph-update`, which can:
47What follows is a summary of the scrys available in graph-store
47What follows is a summary of the scrys available in graph-store
49<!-- enhancement: add examples -->
49<!-- enhancement: add examples -->
50+<!-- enhancement: add refrences to relevant sections in data structures explanation -->
54−- Fetch tag queries
53+### Export State
57−- Fetch tags
55+Obtain a vase of the current state of graph-store as a noun
58− `/x/tag-queries/tags`
60−- Archive a specific graph by resource
57+* Path: `/x/export`
61− `/x/archive/[ship]/[name]`
58+* Output Type: `network:store`
63−- Fetch the update log by resource
60+### Fetch keys
64− `/x/update-log/[ship]/[name]`
66−- Fetch the latest entry in the update log by resource
62+Fetch the resources of all graphs that graph-store is currently tracking
67− `/x/update-log/[ship]/[name]/latest`
69−- Fetch a subset of the update log
64+* Path: `/x/keys`
70− `/x/update-log/[ship]/[name]/subset/[start]/[end]`
65+* Output Type: `(set resource)`
72−- Fetch a specific graph by resource
67+### Fetch tag queries
73− `/x/graph/[ship]/[name]`
75−- Request the mark of a graph
69+Fetch the available tag queries from graph-store
76− `/x/graph/[ship]/[name]/mark`
78−- Request a subset of the graph
71+* Path: `/x/tag-queries`
79− `/x/graph/[ship]/[name]/subset/[mode]/[start]/[end]`
72+* Output Type: `tag-queries`
81−- Check if node exists
74+### Fetch tags
82− `/x/graph/[ship]/[name]/node/exists/[index+]`
84−- Request a node
76+Fetch all available tags from graph-store
85− `/x/graph/[ship]/[name]/node/index/[mode]/[index+]`
87−- Request a node's children
78+* Path: `/x/tag-queries/tags`
88− `/x/graph/[ship]/[name]/node/children/[mode]/[start]/[end]/[index+]`
79+* Output Type: `(list term)`
90−- Request a node's siblings
81+### Fetch the update log by resource
91− `/x/graph/[ship]/[name]/node/siblings/[direction]/[mode]/[count]/[index+]`
83+This returns the full update log for the graph associated with the given resource.
85+* Path: `/x/update-log/[ship]/[name]`
87+ * **ship** (`ship`) - The ship of the resource.
88+ * **name** (`@tas`) - The name of the resource.
89+* Output Type: `update-log:store`
91+### Fetch time of the latest log entry by resource
93+Fetch the time of the latest log entry by resource, if the update-log for the given resource exists.
95+* Path: `/x/update-log/[ship]/[name]/latest`
97+ * **ship** (`ship`) - The ship of the resource.
98+ * **name** (`@tas`) - The name of the resource.
99+* Output Type: `(unit time)`
101+### Fetch a subset of the update log
103+* Path: `/x/update-log/[ship]/[name]/subset/[start]/[end]`
105+ * **ship** (`ship`) - The ship of the resource.
106+ * **name** (`@tas`) - The name of the resource.
107+ * **start** and **end** (`@da`) - all logs after **start** and before **end** are to be included in the result
108+* Output Type: `update-log:store`
110+### Fetch a specific graph by resource
112+Returns the full graph for a given resource.
114+* Path: `/x/graph/[ship]/[name]`
116+ * **ship** (`ship`) - The ship of the resource.
117+ * **name** (`@tas`) - The name of the resource.
118+* Output Type: `update:store`, `%add-graph`
121+### Request the mark of a graph
123+Returns the mark associated a given graph, if one exists.
125+* Path: `/x/graph/[ship]/[name]/mark`
127+ * **ship** (`ship`) - The ship of the resource.
128+ * **name** (`@tas`) - The name of the resource.
129+* Output Type: `(unit mark)`
131+### Request a subset of the graph
133+Returns a subset of nodes from a graph, with or without descendants, optionally filtering for ones that fall between the start and end indexes.
135+* Path: `/x/graph/[ship]/[name]/subset/[mode]/[start?]/[end?]`
138+ * **ship** (`ship`) - The ship of the resource.
139+ * **name** (`@tas`) - The name of the resource.
140+ * **mode** (`?(%kith %lone)`) - `%kith` to include descendants, `%lone` to exclude
141+ * **start** and **end** (`(unit atom)`) - Atoms used to start and end the subset. If these are unable to be parsed, the subset will start at the smallest node
142+* Output Type: `update:store` `%add-nodes`
144+### Check if node exists
146+Returns a flag, `%.y` if the node exists and `%.n` otherwise.
148+* Path: `/x/graph/[ship]/[name]/node/exists/[index+]`
150+ * **ship** (`ship`) - The ship of the resource.
151+ * **name** (`@tas`) - The name of the resource.
152+ * **[index+]** `(list atom)`- The index of the node to check. The index should be appended to the path as a list
153+* Output Type: `flag`
157+Returns an `%add-nodes` update containing the node that was requested
159+* Path: `/x/graph/[ship]/[name]/node/index/[mode]/[index+]`
161+ * **ship** (`ship`) - The ship of the resource.
162+ * **name** (`@tas`) - The name of the resource.
163+ * **mode** (`?(%kith %lone)`) - `%kith` to include descendants, `%lone` to exclude
164+ * **[index+]** `(list atom)`- The index of the node being requested. The index should be appended to the path as a list
165+* Output Type: `update:store` `%add-nodes`
167+### Request a node's children
169+Returns a subset of a node's children, with or without descendants, optionally filtering for ones that fall between the start and end indexes.
172+* Path: `/x/graph/[ship]/[name]/node/children/[mode]/[start?]/[end?]/[index+]`
174+ * **ship** (`ship`) - The ship of the resource.
175+ * **name** (`@tas`) - The name of the resource.
176+ * **mode** (`?(%kith %lone)`) - `%kith` to include descendants, `%lone` to exclude
177+ * **start** and **end** (`(unit atom)`) - Atoms used to start and end the subset. If these are unable to be parsed, the subset will start at the smallest node
178+ * **[index+]** `(list atom)`- The index of the node being requested. The index should be appended to the path as a list
180+* Output Type: `update:store` `%add-nodes`
183+### Request a node's siblings
185+<!-- todo figure out behavior of %newest and %oldest -->
187+* Path: `/x/graph/[ship]/[name]/node/siblings/[direction]/[mode]/[count]/[index+]`
189+ * **ship** (`ship`) - The ship of the resource.
190+ * **name** (`@tas`) - The name of the resource.
191+ * **direction** (`?(%older %newer %oldest %newest)`)-
192+ + `%newer` - load the siblings with keys larger than the requested node
193+ + `%older` - load the siblings with keys smaller than the requested node
194+ + `%newest` - load the siblings with the largest keys
195+ + `%oldest` - load the siblings with the largest keys
196+ * **mode** (`?(%kith %lone)`) - `%kith` to include descendants, `%lone` to exclude
197+ * **count** (`atom`) - a limit to the number of nodes to return
198+ * **[index+]** `(list atom)`- The index of the node being requested. The index should be appended to the path as a list
199+* Output Type: `update:store` `%add-nodes`
93−- Request a node's firstborn child
201+### Request a node's firstborn child
203+<!-- todo explanation -->
94− `/x/graph/[ship]/[name]/node/firstborn/[index+]`
205+* Path: `/x/graph/[ship]/[name]/node/firstborn/[index+]`
207+ * **ship** (`ship`) - The ship of the resource.
208+ * **name** (`@tas`) - The name of the resource.
209+ * **[index+]** `(list atom)`- The index of the node being requested. The index should be appended to the path as a list
211+* Output: `update:store` `%add-nodes`
213+### Request nodes, depth first
215+* Path: `/x/graph/[ship]/[name]/node/depth-first/[count]/[start]`
218+ * **ship** (`ship`) - The ship of the resource.
219+ * **name** (`@tas`) - The name of the resource.
220+ * **count** (`(unit atom)`) - a limit to the number of nodes to return
221+ * **start** (`(unit atom)`) - the index fragment to start at
223+* Output Type: `update:store` `%add-nodes`
226+### Fetch a specific graph by resource
228+<!-- todo should we even document this -->
230+Note: this is equivalent to `/x/graph/[ship]/[name]`
232+* Path: `/x/archive/[ship]/[name]`
234+ * `[ship]` - The ship of the resource. `ship`
235+ * `[name]` - The name of the resource. `@tas`
236+* Output Type: `graph-update`, `[%add-graph]`
96−- Request nodes, depth first
97− `/x/graph/[ship]/[name]/node/depth-first/[count]/[start]`
99## Agent State
239## Agent State