pico-engine 1.9.4 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,362 @@
1
+ # Scatter-Gather
2
+
3
+ Sometimes one pico needs many others to do something, and then needs all the answers together. A fleet pico wants a report from every vehicle pico. A course pico wants a grade from every section. A coordinator wants a vote from every member.
4
+
5
+ The **scatter-gather** pattern does this with events alone, so nobody waits on anybody. This lesson explains the pattern with the problem that taught it to us, and builds a runnable version.
6
+
7
+ ## Objectives
8
+
9
+ When you finish you will be able to:
10
+
11
+ - explain why a synchronous request-response solution breaks as the number of picos grows
12
+ - scatter an event to a computed list of picos, and gather the answers with an aggregator
13
+ - use a **correlation number** to keep concurrent conversations apart
14
+ - add a timeout, and say why it is a safety net and not the way the work finishes
15
+ - compare event recipient lists, content-based routing, and registration as ways to decide who gets an event
16
+
17
+ **Before you begin**, finish [Pico-Based Systems](/lessons/pico-based-systems) and [Relationships](/lessons/relationships). The example sends events to children, and the routing examples use relationships.
18
+
19
+ ## The problem
20
+
21
+ <img src="/lessons/_media/1185976-26315821-fuse.jpg" alt="Fuse Logo" width="50%">
22
+
23
+ Fuse was an open-source connected-car platform built with picos. Every week it sent the fleet owner a report: the trips and fuel fill-ups of each vehicle in the period, summed for each vehicle and then for the fleet. Here's the start of a weekly report for one fleet:
24
+
25
+ <img src="/lessons/_media/1185976-21289230688-fuse-weekly-report.png" alt="Start of a Fuse weekly report, with trip and fill-up details for each vehicle" width="50%">
26
+
27
+ The owner was a pico, so was the fleet, and so was each vehicle. Each was independent and addressable, kept its own data, and answered queries (functions) and events (rules). They talked to one another directly, with nothing in between.
28
+
29
+ ## The synchronous solution
30
+
31
+ The straightforward way is for the fleet to *ask* each vehicle for its details, wait for every reply, format the report, and tell the owner that it's ready:
32
+
33
+ ```krl
34
+ fleetDetails = function() {
35
+ wrangler:children().map(function(vehicle) {
36
+ wrangler:picoQuery(vehicle{"eci"}, "com.example.vehicle", "summary", {})
37
+ })
38
+ }
39
+ ```
40
+
41
+ That process looks like this. The owner sends `periodic_report` to the fleet; a rule calls a function that queries each vehicle over HTTP; once every vehicle has answered, the fleet formats the report and tells the owner it's ready:
42
+
43
+ <img src="/lessons/_media/1185976-21293069658-synchronous.png" alt="Synchronous request-response: the fleet queries each vehicle in turn and waits for every reply before finishing the report" width="50%">
44
+
45
+ Programmers who've used an API will find that familiar. It works so long as every vehicle answers promptly. A query waits for its answer, so the fleet pico is stuck for the sum of all the delays, and it can't handle anything else meanwhile. Vehicles on other engines are queried over the network, where timeouts have to be short, and one slow vehicle gets missed. With a few vehicles that's rare. With ten, the chance that at least one is late gets good, and with a hundred it's routine.
46
+
47
+ Longer timeouts only hide the problem. Making each vehicle faster helps, but there is always something that can be slow: the network, a busy engine, a database. If a synchronous request-response were your only tool, this would be a serious problem. It isn't your only tool.
48
+
49
+ ## The scatter-gather solution
50
+
51
+ Use events, and let every pico work at its own pace. Vaughn Vernon describes the pattern in *Reactive Messaging Patterns with the Actor Model*: get a number of actors to do something, then aggregate what they send back. Here:
52
+
53
+ 1. The owner (or anything else) sends the fleet `report:requested`. Having sent it, the sender is free to do other things.
54
+ 2. A rule in the fleet **scatters** a `report:vehicle_report_requested` event to each vehicle, whether there are 1 or 100. These are asynchronous too, and under no time pressure.
55
+ 3. Each vehicle builds its report and sends `report:vehicle_report_created` to the fleet.
56
+ 4. A rule in the fleet **gathers** them, one at a time, as they arrive.
57
+ 5. Another rule checks whether every vehicle has answered. When all have, the fleet finishes the report.
58
+
59
+ There are no queries in this flow, only events. Events go to a pico, not to a particular rule: each pico has its own event bus, and any rule that selects the event runs. A rule doesn't need to know who raised the event, or what else is listening.
60
+
61
+ Fuse's weekly report used exactly this pattern, with a timer added as a safety net. Each oval is a pico, each rounded box a rule, and each arrow an event. Picos with the same name are the same pico, drawn again to show the next step:
62
+
63
+ <img src="/lessons/_media/1185976-21293982299-scatter-gather.png" alt="Fuse periodic report: the owner asks the fleet, the fleet scatters a request to each vehicle, vehicles send reports back, the fleet gathers them and sends the finished report to the owner, with a two-minute timer as a safety net" width="50%">
64
+
65
+ ## The messy details
66
+
67
+ Two problems have to be solved for this to be reliable.
68
+
69
+ **Overlap.** A second report might start before the first has finished. Each run therefore carries a unique **correlation number**, `rcn`. Every rule that sees it passes it along and files its data under it, so two reports in flight at once never get mixed up. (Reports run once a week and almost never overlap, but it's a good habit: independent conversations should be kept independent.)
70
+
71
+ **Loss.** The "is everyone in?" check depends on events from vehicles. Delivery isn't guaranteed: a pico might be down, an engine unreachable, a pico deleted mid-conversation. If one never answers, the report never finishes. There are several tactics:
72
+
73
+ - Accept it: tell owners that a report sometimes fails, and let someone ask for it again.
74
+ - Set a timeout and carry on, producing the report with some vehicles missing.
75
+ - Set a timeout and re-send the request to the vehicles that haven't answered, and give up (carry on without them) after some number of retries.
76
+
77
+ Fuse used the second. Picos have no clock tick of their own. They react to events, so if you need a timer you schedule an event for later. Two minutes was plenty. Scheduling a short, recurring event to make a "tick" is possible, but usually unnecessary and wasteful.
78
+
79
+ > **The timeout is a safety net.** The normal path is driven entirely by events: the last answer arrives, the check fires, the report finishes. The timer only matters when something went wrong. Don't schedule an event to wait for work to finish. Chain steps with events instead.
80
+
81
+ ## The pieces
82
+
83
+ Here is the fleet. It's a ruleset for a pico whose children are vehicles. The rules appear in the order they run, one for each step above.
84
+
85
+ ### Correlating events
86
+
87
+ A **correlation identifier** links the two halves of an asynchronous conversation. It is an event attribute, any string that's unique within the conversation, and the sender of the first event expects it back in the reply. Rules also use it as a key in persistent state, so each conversation's data is separate.
88
+
89
+ <img src="/lessons/_media/1185976-25264445563-event-correlation.png" alt="Event correlation: a request carries a correlation number that comes back with the reply, so overlapping conversations stay separate" width="50%">
90
+
91
+ ```krl
92
+ // 1. Start: correlate the work, remember who we expect, set a safety timer.
93
+ rule start_report {
94
+ select when report requested
95
+ pre {
96
+ rcn = event:attr("rcn") || random:uuid()
97
+ expected = vehicles().map(function(v) { v{"name"} })
98
+ }
99
+ always {
100
+ ent:reports{rcn} := {"expected": expected, "received": {}}
101
+ raise report event "scatter" attributes {"rcn": rcn}
102
+ schedule report event "timer_expired"
103
+ at time:add(time:now(), {"minutes": 2})
104
+ attributes {"rcn": rcn}
105
+ }
106
+ }
107
+ ```
108
+
109
+ - `rcn` is taken from the event if the caller supplied one (so a retry can reuse a number), and otherwise generated with `random:uuid()`.
110
+ - The rule stores the fleet's expectations under that number: the vehicles it's waiting for, and a map for what's received.
111
+ - In the postlude it raises `report:scatter` to start the work and schedules `report:timer_expired`, both carrying the number.
112
+
113
+ Any rule that sees an `rcn` must pass it on. Future versions of Wrangler may automate more of this.
114
+
115
+ ### Event recipient lists
116
+
117
+ The simplest routing is to keep a list of picos and send the same event to each of them, like the **To:** line of an email. The list can be fixed, or computed, so that the pico acts as an event router. Here the list is the fleet's current children:
118
+
119
+ <img src="/lessons/_media/1185976-25867495936-event-recipient-list.png" alt="Event recipient list: one pico sends the same event to every pico on a list" width="50%">
120
+
121
+ ```krl
122
+ // 2. Scatter: one event per vehicle, from a computed recipient list.
123
+ rule scatter {
124
+ select when report scatter
125
+ foreach vehicles() setting(vehicle)
126
+ event:send({
127
+ "eci": vehicle{"eci"},
128
+ "domain": "report",
129
+ "type": "vehicle_report_requested",
130
+ "attrs": {"rcn": event:attr("rcn")}
131
+ })
132
+ }
133
+ ```
134
+
135
+ - `foreach` runs the rest of the rule once for each vehicle that `vehicles()` returns, setting `vehicle` each time. If vehicles are added or removed, the next report just uses the new list.
136
+ - `event:send` goes in the action block. It sends `report:vehicle_report_requested` over the family channel to each vehicle.
137
+ - The number goes along with it.
138
+
139
+ The vehicle pico does its part, and it can take as long as it likes:
140
+
141
+ ```krl
142
+ ruleset com.example.vehicle {
143
+ meta {
144
+ name "Vehicle"
145
+ use module io.picolabs.wrangler alias wrangler
146
+ shares summary
147
+ }
148
+ global {
149
+ /**
150
+ * What this vehicle has done.
151
+ * @returns Map
152
+ */
153
+ summary = function() {
154
+ {"trips": ent:trips.defaultsTo(0), "miles": ent:miles.defaultsTo(0)}
155
+ }
156
+ }
157
+
158
+ rule produce_vehicle_report {
159
+ select when report vehicle_report_requested rcn re#(.+)# setting(rcn)
160
+ event:send({
161
+ "eci": wrangler:parent_eci(),
162
+ "domain": "report",
163
+ "type": "vehicle_report_created",
164
+ "attrs": {"rcn": rcn, "vehicle": wrangler:name(), "details": summary()}
165
+ })
166
+ }
167
+ }
168
+ ```
169
+
170
+ It sends the answer to its parent with the number and its name, so the fleet can tell who replied.
171
+
172
+ ### Aggregators
173
+
174
+ An **aggregator** collects events and, when it has enough, raises an event or takes another action. The fleet's is two rules: one collects, and one decides.
175
+
176
+ <img src="/lessons/_media/1185976-25867268766-event-aggregation.png" alt="Event aggregation: answers arrive one by one; when enough have been collected, the aggregator raises a ready event" width="50%">
177
+
178
+ ```krl
179
+ // 3. Gather: file each answer under its correlation number.
180
+ rule catch_vehicle_report {
181
+ select when report vehicle_report_created
182
+ pre {
183
+ rcn = event:attr("rcn")
184
+ open = reports() >< rcn
185
+ }
186
+ if open then noop()
187
+ fired {
188
+ ent:reports{[rcn, "received", event:attr("vehicle")]} := event:attr("details")
189
+ raise report event "vehicle_report_added" attributes {"rcn": rcn}
190
+ }
191
+ }
192
+ ```
193
+
194
+ - The rule files the vehicle's details under `[rcn, "received", vehicle name]`, so overlapping reports can't interfere, and a vehicle that answers twice just overwrites itself.
195
+ - The rule only acts if the report is still open (`reports() >< rcn`). An answer that arrives after the report has finished is ignored.
196
+ - It raises `report:vehicle_report_added` with the number so another rule can decide.
197
+
198
+ ```krl
199
+ // 4. Check: is everyone in?
200
+ rule check_report_status {
201
+ select when report vehicle_report_added
202
+ pre {
203
+ rcn = event:attr("rcn")
204
+ report = ent:reports{rcn}
205
+ still_waiting = report{"expected"}.defaultsTo([]).difference(report{"received"}.defaultsTo({}).keys())
206
+ }
207
+ if not report.isnull() && still_waiting.length() == 0 then noop()
208
+ fired {
209
+ raise report event "ready" attributes {"rcn": rcn}
210
+ }
211
+ }
212
+ ```
213
+
214
+ - The prelude works out which expected vehicles haven't answered. Each is in `expected` but not among the keys of `received`.
215
+ - If none is missing, the rule fires and raises `report:ready`. Otherwise it does nothing: there's no waiting, no loop, and the next answer will run this rule again.
216
+
217
+ ### Dealing with failure
218
+
219
+ Because events may be lost, asynchronous systems have to be prepared to deal with failure. A timer, a retry, or both:
220
+
221
+ <img src="/lessons/_media/1185976-26168873862-event-failure.png" alt="Dealing with failure: a scheduled timer retries missing vehicles, then finishes the report with what it has" width="50%">
222
+
223
+ The timer was scheduled when the report began. When it expires, the rule sees whether the report is still open, and if it is, raises the same `report:ready` event, marked `timed_out`:
224
+
225
+ ```krl
226
+ // The timer is a safety net, not the way the work normally finishes.
227
+ rule timer_expired {
228
+ select when report timer_expired
229
+ pre {
230
+ rcn = event:attr("rcn")
231
+ }
232
+ if reports() >< rcn then noop()
233
+ fired {
234
+ raise report event "ready" attributes {"rcn": rcn, "timed_out": true}
235
+ }
236
+ }
237
+ ```
238
+
239
+ Whichever comes first, the last answer or the timer, ends in `report:ready`. The rule that finishes the report has to make sure it only does so once:
240
+
241
+ ```krl
242
+ // 5. Finish once, however we got here.
243
+ rule finish_report {
244
+ select when report ready
245
+ pre {
246
+ rcn = event:attr("rcn")
247
+ report = ent:reports{rcn}
248
+ missing = report{"expected"}.defaultsTo([]).difference(report{"received"}.defaultsTo({}).keys())
249
+ }
250
+ if not report.isnull() then noop()
251
+ fired {
252
+ ent:completed{rcn} := {
253
+ "details": report{"received"},
254
+ "missing": missing,
255
+ "time": time:now()
256
+ }
257
+ clear ent:reports{rcn}
258
+ }
259
+ }
260
+ ```
261
+
262
+ It runs only if `ent:reports{rcn}` still exists, and it clears it. So a late answer, or a timer that expires after the report is done, finds nothing to do. The finished report lists the `details` it has and which vehicles are `missing`, so a reader knows what it's made of.
263
+
264
+ To retry instead of just continuing, have `timer_expired` raise `report:scatter` again for only the missing vehicles (the same `rcn`), count the attempts, schedule the timer again, and finish after the limit. Fuse did this: up to two retries, two minutes apart, and then a report with what it had.
265
+
266
+ ### Content-based event routing
267
+
268
+ Another way to decide who gets an event is by what it says. The routing pico knows several others and chooses by the event's domain, type, attributes, or its own state. A Fuse fleet could have more than one owner and needed to keep an owner informed by routing certain events to one:
269
+
270
+ <img src="/lessons/_media/1185976-25260450274-event-routing.png" alt="Content-based event routing: the router chooses a destination from the event's content and the pico's state" width="50%">
271
+
272
+ ```krl
273
+ // Content-based routing: the event decides where it goes.
274
+ rule route_to_owner {
275
+ select when fleet new_trip
276
+ or fleet reminders_ready
277
+ or fleet email_for_owner
278
+ pre {
279
+ owner = relationship:established("Tx_role", "owner").head()
280
+ }
281
+ if owner then
282
+ event:send({
283
+ "sub": owner,
284
+ "domain": "fleet",
285
+ "type": event:type(),
286
+ "attrs": event:attrs
287
+ })
288
+ }
289
+ ```
290
+
291
+ - The event expression says which events get routed. It's fixed when the rule is written. To route on something computed, chain rules.
292
+ - `relationship:established("Tx_role", "owner")` finds the relationships whose other end is an owner. `head()` takes the first. To tell every owner, loop over them with `foreach`.
293
+ - `event:send` with `"sub"` sends over the relationship. The type and attributes of the incoming event go along unchanged.
294
+
295
+ ### Registration
296
+
297
+ The most general routing is a directory. Picos send a registration event saying who they are and what they care about, and the directory routes events to those that have registered for them. The directory can be a special pico in a large system, or a ruleset in a pico that does other things too. A directory also lets a pico change its channel for security without losing service, and lets a pico move without losing messages.
298
+
299
+ <img src="/lessons/_media/1185976-26210449896-pico-registry.png" alt="Pico registration: picos register with a directory; the directory routes events to those that have registered for a topic" width="50%">
300
+
301
+ ```krl
302
+ // Registration: picos say what they want to hear about.
303
+ rule register_pico {
304
+ select when registry pico_registered
305
+ topic re#(.+)#
306
+ eci re#(.+)#
307
+ setting(topic, eci)
308
+ always {
309
+ ent:registrations{[topic, eci]} := event:attr("name")
310
+ }
311
+ }
312
+ ```
313
+
314
+ ```krl
315
+ rule route_to_registered {
316
+ select when fleet events_to_route
317
+ or fleet another_event_to_route
318
+ foreach registered(event:attr("topic")) setting(eci)
319
+ event:send({
320
+ "eci": eci,
321
+ "domain": "fleet",
322
+ "type": event:type(),
323
+ "attrs": event:attrs
324
+ })
325
+ }
326
+ ```
327
+
328
+ The first rule files each registrant under its topic. The second sends an incoming event to every pico registered for the event's `topic`. A registrar goes a step further: it manages the registry on behalf of the picos, watching `wrangler:child_initialized` and `wrangler:child_deleted` and registering and deregistering as they come and go. The picos needn't know the registry exists.
329
+
330
+ ## Try it
331
+
332
+ Make a fleet pico with two or three children. Install `com.example.vehicle` in each child, and `com.example.fleet` in the parent. The easy way is to use the chain from [Pico-Based Systems](/lessons/pico-based-systems): `new_child_request`, then `child_initialized`, then `install_ruleset_request`.
333
+
334
+ On the fleet's Testing tab, raise `report:requested`. Query `completed` and you'll see one report with every vehicle's details, an empty `missing` list, and the correlation number as its key. Then try it the hard way:
335
+
336
+ - Uninstall `com.example.vehicle` from one child and raise `report:requested` again. The report completes after the timer expires, with that vehicle in `missing`.
337
+ - Raise `report:requested` twice quickly. There are two numbers and two independent reports.
338
+
339
+ ## Conclusion
340
+
341
+ Recipient list plus aggregator is the scatter-gather pattern in full:
342
+
343
+ <img src="/lessons/_media/1185976-25592606980-scatter-gather-pattern.png" alt="Scatter-gather: scatter events to many picos from a recipient list, then gather their answers with an aggregator" width="50%">
344
+
345
+ Scatter-gather adds a few rules over the synchronous version, and each is short and does one thing. What you get for it:
346
+
347
+ - **Reliability.** The synchronous version fails when any vehicle is slow. This one finishes even when one is dead.
348
+ - **Better use of the fleet pico.** It doesn't sit waiting. It handles other events while the vehicles work, and takes the answers as they arrive.
349
+ - **No locks.** The fleet pico may get answers from many vehicles at once, but they queue and are handled one at a time. Because each pico is independent, concurrent processing needs no locks, inside a pico or between picos. This is a property of actor systems, and picos are actors.
350
+
351
+ Vernon's book is a good companion. Its language and framework (Scala and Akka) are different, but the concepts carry over directly to picos.
352
+
353
+ ## Related
354
+
355
+ - [Child pico tasks](/cookbook/child_tasks/): a pico per job, with a task id and no waiting
356
+ - [Querying another pico](/developing/querying-another-pico): when a synchronous query is the right tool
357
+ - [Relationships](/wrangler/relationships) and [The wrangler ruleset](/wrangler/wrangler): the events and functions used here
358
+ - [Gossip](/lessons/gossip): an advanced lab in which picos exchange state by events
359
+
360
+ ---
361
+
362
+ <small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1185976) (Reactive Programming Patterns: Scatter Gather, last edited there 2021-03-06), and rewritten for this engine. The Fuse examples are now written as a small fleet and vehicle.</small>
@@ -76,11 +76,12 @@ Example templates: [`config.example.json`](../../config.example.json), [`config.
76
76
  | `port` | number | HTTP listen port. Default `3000`. |
77
77
  | `baseUrl` | string | Public origin (no trailing slash): WebAuthn, did:webvh, links. Default `http://localhost:3000`. |
78
78
  | `allowSelfSignup` | boolean | Open registration after bootstrap. Default `false` (invite-only). |
79
- | `allowLocalhostChannelBypass` | boolean | Allow `/c/*` from localhost without passkey (dev MCP, KRL HTTP loops). Default `true`. Set `false` in production behind TLS. |
79
+ | `allowLocalhostChannelBypass` | boolean | Allow `/c/*`, `/api/dev/local`, and `/api/try-it` from a **direct loopback** socket without a passkey or the internal token. Default `false`. A request with `X-Forwarded-For`, `X-Real-IP`, or `Forwarded` is never treated as local. The dev MCP uses `$PICO_ENGINE_HOME/internal-token` instead. |
80
80
  | `wildcardSkyRequireBearer` | boolean | Require OAuth bearer on `/sky/*` for channels with unrestricted `*.*` allow rules. Default `false` (1.8 opt-in hardening). |
81
81
  | `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
82
82
  | `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
83
83
  | `logMirror` | boolean | When **`logToStdout`** is true: also write structured JSON lines to **`$PICO_ENGINE_HOME/pico-engine.log`** for operators. Default **`true`**. Set **`false`** on EFS + Fargate to avoid mirror-file churn (then use CloudWatch from stdout, or set **`logFile`** to a writable path). The Developer UI **Logging** tab reads an in-memory ring and does not need this file. **Env:** `PICO_ENGINE_LOG_MIRROR` (`true`/`1` / `false`/`0`). |
84
+ | `show_tryit_menu` | string | Where the Developer UI shows the **Try It!** tab: **`off`** (nowhere, and `/api/try-it` lists no demos), **`root_only`** (the root pico only), or **`all`** (every pico). Default **`root_only`**. **Env:** `PICO_ENGINE_SHOW_TRYIT_MENU`. |
84
85
  | `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
85
86
  | `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
86
87
  | `globalQueryDeny` | array | Same for queries. |
@@ -105,6 +106,8 @@ These env overrides cover config path, data dir, port, public URL, and a few log
105
106
  | `PICO_ENGINE_LOG_FILE` | Log file path, or `stdout` / `-` / `0` / empty for stdout-only |
106
107
  | `PICO_ENGINE_LOG_MIRROR` | When stdout-only: `false` / `0` disables writing `$PICO_ENGINE_HOME/pico-engine.log` (config: **`logMirror`**). The Logging tab does not read that file |
107
108
  | `PICO_ENGINE_LOG_RING` | How many recent transactions per pico the Logging tab keeps in memory. Default **200**. A restart clears the ring |
109
+ | `PICO_ENGINE_SHOW_TRYIT_MENU` | `off`, `root_only` (default), or `all`: where the Developer UI shows the **Try It!** tab (config: **`show_tryit_menu`**) |
110
+ | `PICO_ENGINE_DEMOS_DIR` | A directory to serve as `demos/` (at `/krl/demos/`) instead of the copy shipped with the engine, such as the `demos/` folder of a pico-engine checkout you're editing |
108
111
 
109
112
  ---
110
113
 
@@ -135,7 +138,7 @@ Mesh state lives under `home`:
135
138
 
136
139
  - One writer per data directory (LevelDB).
137
140
  - **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config. Set **`logMirror: false`** if you do not want the engine writing `pico-engine.log` on EFS (stdout → CloudWatch only).
138
- - Set `allowLocalhostChannelBypass` to **false** on public deployments.
141
+ - `allowLocalhostChannelBypass` defaults to **false**. Leave it false on public deployments. The dev MCP reads `internal-token` from the engine data directory (on Docker, the host path of the `home` volume).
139
142
 
140
143
  Detailed checklists: package **README** § Containers / Fargate.
141
144
 
@@ -204,9 +207,11 @@ Owner UI uses the **UI channel** (passkey). Automation uses **OAuth** on `/sky/*
204
207
  | Path | Auth | Use |
205
208
  |------|------|-----|
206
209
  | `/` | Browser | Developer UI |
207
- | `/c/*` | Passkey session (localhost bypass optional) | Developer UI (browser). **Discouraged** for automation and third-party apps — use `/sky/*` or mesh MCP instead. |
210
+ | `/c/*` | Passkey session, or `X-Pico-Internal` (dev MCP) | Developer UI (browser). **Discouraged** for automation and third-party apps — use `/sky/*` or mesh MCP instead. |
208
211
  | `/sky/*` | Channel policy ± OAuth bearer | Events, queries, integrators |
209
- | `/mcp/:eci` | OAuth bearer | Mesh MCP (Streamable HTTP) |
212
+ | `/mcp/:eci` | OAuth bearer | Mesh MCP (Streamable HTTP). A missing token is `401` with `WWW-Authenticate: Bearer resource_metadata="…"`. |
213
+ | `/.well-known/oauth-authorization-server` | Public | OAuth authorization-server metadata (RFC 8414) for MCP clients |
214
+ | `/.well-known/oauth-protected-resource/mcp/:eci` | Public | Protected-resource metadata (RFC 9728) for that channel's MCP URL |
210
215
  | `/auth/*` | WebAuthn flows | Registration, login |
211
216
 
212
217
  Local dev MCP: `pico-engine mcp --stdio` — not exposed on hosted load balancers; see [1.8 plan § MCP](https://github.com/Picolab/pico-engine/blob/master/docs/release/1.8.md) (deployment table).
@@ -216,7 +221,7 @@ Local dev MCP: `pico-engine mcp --stdio` — not exposed on hosted load balancer
216
221
  ## Agents and KRL authoring
217
222
 
218
223
  - **`krl-check`** on ruleset files before install.
219
- - **Dev MCP** (stdio): validate, install, flush, raise, query — same mesh as the UI when `PICO_ENGINE_HOME` / config match.
224
+ - **Dev MCP** (stdio): validate, install, flush, raise, query — same mesh as the UI when `PICO_ENGINE_HOME` / config match. It runs the Try It! demos too (`list_try_it_demos`, `run_try_it_demo`, `try_it_status`), and serves the cookbook and Developing with Picos pages as `pico://docs/cookbook/<folder>/README`, `…/instructions`, and `pico://docs/developing/<page>`.
220
225
  - **Docs for LLMs:** [`llms.txt`](llms.txt), [`llms-full.txt`](llms-full.txt), [`openapi.yaml`](openapi.yaml). Regenerate after doc edits: `npm run generate:llms` at repo root.
221
226
 
222
227
  ---
@@ -25,7 +25,7 @@ Three kinds of persistence distinguish picos from most other programming models:
25
25
  | Part | What it is |
26
26
  |------|------------|
27
27
  | **Rulesets and event bus** | Behavior is installed as KRL rulesets, loaded by URL and compiled to JavaScript. A rule is event-condition-action: `select when` an event expression matches, evaluate a condition, act, then a postlude that updates state and raises further events. Every incoming event is raised on the pico's internal bus; a salience graph routes it to listening rules, so installing a ruleset subscribes its rules automatically. |
28
- | **Event-query API** | Not RESTful. The **Sky Event API** delivers events; the **Sky Cloud/Query API** calls shared functions. It is a *meta-API*: a pico's concrete API is whatever its installed rulesets provide, and it can change over the pico's life. |
28
+ | **Event-query API** | Not RESTful. Events change state; queries call shared functions. It is a *meta-API*: a pico's concrete API is whatever its installed rulesets provide, and it can change over the pico's life. Sky is the current [Event Exchange Protocol](/exp/) version (`/sky/event`, `/sky/query`). |
29
29
  | **State: entity variables and PDS** | `ent:` variables are scoped to each ruleset (a closure over its data). The **Pico Data Store** (default since 1.4) is the shared data plane on every pico — profile, namespaced general data, per-ruleset settings — written by `pds` events, read by shared functions. |
30
30
  | **Channels (ECIs)** | As many channels as a pico needs, each with an Event Channel Identifier and its own event/query **policy**. Channels are non-correlatable addresses and the local authorization gate. A `discovery` channel on every pico lets integrators learn what it can do. |
31
31
  | **Relationships** | Pairwise, bidirectional, policy-gated connections between picos (*subscriptions* before 1.6.2). They form the heterarchical graph applications run on, independent of the parent/child tree and of which engine hosts each pico. |
@@ -60,7 +60,7 @@ The value is the combination: every entity gets a **closure over identity, data,
60
60
  | **Persistent identity** (`did:webvh`, channels) | Relationships that outlive restarts and moves; reputation and history; credentials with a durable subject; revocable delegation; a lifecycle that follows the thing across owners. Why SPIFFE was set aside: it names replaceable processes; picos are actors that last. |
61
61
  | **Persistent state and availability** (entity vars, PDS) | Databaseless programming; the running system *is* the design, visible live in the developer UI. Data control at the ruleset grain: delete the trip service before transferring a vehicle, keep the maintenance records. Twins keep working while the owner is offline. |
62
62
  | **Rules on an event bus** | Each rule is a microservice for one entity. Functionality accretes — install a ruleset and its rules start listening. Correlation ids, scatter-gather, guard rules, scheduled retries, and routed error events make failure-tolerant asynchrony the default. |
63
- | **Event-query meta-API + discovery** | A pico's API is discoverable at runtime. Home Assistant turns discovery bindings into devices and services; the MCP interface turns them into LLM tools, gated to the rulesets actually installed. |
63
+ | **Event-query meta-API + discovery** | A pico's API is discoverable at runtime. Home Assistant turns discovery bindings into devices and services; the MCP interface turns them into LLM tools, gated to the rulesets actually installed. Details: [Event Exchange Protocol](/exp/). |
64
64
  | **Channels with policy** | Capability-style security: an ECI is permission to do what its policy allows and nothing more. Separate channels prevent correlation, scope webhooks to one endpoint, and let discovery filter bindings per caller. |
65
65
  | **Typed, pairwise relationships** | Heterarchical graphs across the tree and across engines. Rights are *relationships*, not attributes: a fleet can have two owners, a truck can be lent with attenuated rights, a community can accept members from other meshes. The **introduction pattern** — an existing relationship brokers a new one — generalizes to delegation, transfer, and ReBAC. |
66
66
  | **Tree + Wrangler** | Programmatic lifecycle: picos create, initialize, and delete picos; prototypes stamp out configured children. Admin rights follow the tree; everything else is conferred by policy. |
@@ -112,6 +112,6 @@ Moving picos between engines ([pico-move.md](./pico-move.md)), pico-level schema
112
112
 
113
113
  **Repos and docs:** this folder and `MEMORY.md`; [manifold-api](https://github.com/Picolab/manifold-api) (`README.md`, `docs/Manifold.md`, `docs/Managing_PDS.md`); [sensor-network](https://github.com/windley/sensor-network); [MCPforEXP](https://github.com/picolab/MCPforEXP).
114
114
 
115
- **Confluence documentation** — the [Pico Labs developer site](https://picolabs.atlassian.net/wiki/spaces/docs/overview) is the reference manual for everything above. Start here: [Pico Engine Quickstart](https://picolabs.atlassian.net/wiki/spaces/docs/pages/19791878) · [Pico Programming Lessons](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1185969). Engine and Wrangler: [Pico Engine](https://picolabs.atlassian.net/wiki/spaces/docs/pages/6356996) · [Wrangler](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1686929547) · [Picos API](https://picolabs.atlassian.net/wiki/spaces/docs/pages/761593879) · [Managing Channels](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403288) · [Managing Pico Lifecycle](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403290). KRL: [KRL Manual](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189890) · [Libraries](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189596) · [KRL Cookbook](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1190497). Identity: [Identity System](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3962044419) · [DIDs — Pico Identity](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4033413122) · [Relationships](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4032102406). Platform: [Manifold](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907190800) · [Pico Data Store](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907289100).
115
+ **Docs in this repo** — start with the [Programming lessons](/lessons/) (Quickstart through Relationships). Engine and Wrangler: [Operator guide](/pico-engine) · [Wrangler](/wrangler/) · [Channels](/wrangler/channels) · [Event Exchange Protocol](/exp/). KRL: [KRL Manual](/krl/) · [Developing with Picos](/developing/) (workflow, tips, misconceptions). Identity and relationships: [Relationships](/wrangler/relationships) · design notes in this folder. Platform: [Manifold](https://github.com/Picolab/manifold-api) (sibling repo). Older Confluence pages that have not been moved yet remain at the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/overview).
116
116
 
117
117
  **Blog (windley.com, tag: picos):** [Fundamental Features of Persistent Compute Objects](https://www.windley.com/archives/2013/10/fundamental_features_of_persistent_compute_objects.shtml) · [Pico APIs: Events and Queries](https://www.windley.com/archives/2013/12/pico_apis_events_and_queries.shtml) · [Complex Pico Structures: Guard Tours](https://www.windley.com/archives/2014/01/complex_pico_structures_guard_tours.shtml) · [Fuse as a Microservice Architecture](https://www.windley.com/archives/2014/07/fuse_as_a_microservice_architecture.shtml) · [Fuse with Two Owners](https://www.windley.com/archives/2014/10/fuse_with_two_owners.shtml) · [Reactive Programming with Picos](https://www.windley.com/archives/2015/11/reactive_programming_with_picos.shtml) · [Reactive Programming Patterns: Examples from Fuse](https://www.windley.com/archives/2016/04/reactive_programming_patterns_examples_from_fuse.shtml) · [Using Picos for BYU's Priority Registration](https://www.windley.com/archives/2017/01/using_picos_for_byus_priority_registration.shtml) · [Announcing Pico Engine 1.0](https://www.windley.com/archives/2021/02/announcing_pico_engine_10.shtml) · [Persistence, Programming, and Picos](https://www.windley.com/archives/2021/02/persistence_programming_and_picos.shtml) · [Ten Reasons to Use Picos](https://www.windley.com/archives/2021/07/ten_reasons_to_use_picos_for_your_next_decentralized_programming_project.shtml) · [Alternatives to the CompuServe of Things](https://www.windley.com/archives/2021/07/alternatives_to_the_compuserve_of_things.shtml) · [Monitoring Temperatures in a Remote Pump House](https://www.windley.com/archives/2023/03/monitoring_temperatures_in_a_remote_pump_house_using_lorawan.shtml) · [Building a Conversational Interface for Manifold](https://www.windley.com/archives/2026/04/building_a_conversational_interface_for_manifold_with_mcp_and_picos.shtml) · [AI Integration in Picos Starts with Events](https://www.windley.com/archives/2026/06/ai_integration_in_picos_starts_with_events.shtml) · [Manifold API and Sensor Network](https://www.windley.com/archives/2026/06/manifold_api_and_sensor_network_two_new_repos.shtml) · [Identity for the Pico Engine](https://www.windley.com/archives/2026/07/identity_for_the_pico_engine.shtml) · [Why Not SPIFFE for Pico Identity?](https://www.windley.com/archives/2026/08/why_not_spiffe_for_pico_identity.shtml) · [Moving My Sensor Network onto Manifold](https://www.windley.com/archives/2026/09/moving_my_sensor_network_onto_manifold.shtml).
@@ -0,0 +1,47 @@
1
+ # Wrangler
2
+
3
+ Wrangler is the operating system for picos. The engine itself provides primitives: picos, channels, events, queries, persistence, identity. Wrangler is a set of KRL rulesets, installed on every pico, that wraps those primitives in events and functions your rulesets use: create and delete child picos, install rulesets, make channels, form relationships with other picos, and keep a pico's profile and data.
4
+
5
+ Use Wrangler rather than the engine's `ctx:` primitives from application rulesets. Wrangler is the supported API for a pico's life cycle. If something you need isn't there, treat it as out of bounds, or [file an engine issue](https://github.com/Picolab/pico-engine/issues).
6
+
7
+ ## The rulesets on every pico
8
+
9
+ The engine installs these on the root pico, and Wrangler installs them on every child it creates:
10
+
11
+ | Ruleset | What it does | Guide | API reference |
12
+ |---------|--------------|-------|---------------|
13
+ | `io.picolabs.wrangler` | A pico's life cycle: child picos, rulesets, channels, and queries to other picos | [The wrangler ruleset](/wrangler/wrangler) | [io.picolabs.wrangler](/rulesets/io.picolabs.wrangler) |
14
+ | `io.picolabs.subscription` | Relationships between picos (called subscriptions before engine 1.6.2) | [Relationships](/wrangler/relationships) | [io.picolabs.subscription](/rulesets/io.picolabs.subscription) |
15
+ | `io.picolabs.pds` | The pico's profile and its shared, namespaced data | [Pico data store](/wrangler/pds) | [io.picolabs.pds](/rulesets/io.picolabs.pds) |
16
+ | `io.picolabs.pico-engine-ui` | What the developer UI needs: its channel, the pico's box, Testing tab history | — | [io.picolabs.pico-engine-ui](/rulesets/io.picolabs.pico-engine-ui) |
17
+
18
+ Channels are the engine's, but Wrangler is how rulesets manage them: see [Managing channels](/wrangler/channels).
19
+
20
+ ## Optional rulesets
21
+
22
+ The engine ships these too, at `/krl/<rid>.krl`, but doesn't install them. Install one from a pico's **Rulesets** tab, or with `wrangler:install_ruleset_request`, when you need it:
23
+
24
+ | Ruleset | What it does | Guide |
25
+ |---------|--------------|-------|
26
+ | `io.picolabs.xmlui` | Pages served from a pico (pico views) and the components they share | [Pico views](/wrangler/xmlui) |
27
+ | `io.picolabs.oauth` | Root pico only: require OAuth access tokens on the mesh's `/sky/*` traffic, and manage OAuth credentials | [OAuth](/wrangler/oauth) |
28
+ | `io.picolabs.portable_subtree` | Export a pico and its children, and import them under another parent, on this engine or another | [Portable subtrees](/wrangler/portable-subtree) |
29
+
30
+ ## Using Wrangler from a ruleset
31
+
32
+ Each Wrangler ruleset works two ways:
33
+
34
+ - **Events.** Raise or send an event that a Wrangler rule selects, such as `wrangler:new_child_request` or `wrangler:install_ruleset_request`. When the work is done, Wrangler raises an event saying so, such as `wrangler:child_initialized` or `wrangler:ruleset_installed`, which your rules can select.
35
+ - **Functions and actions.** Use the ruleset as a module and call what it provides:
36
+
37
+ ```krl
38
+ meta {
39
+ use module io.picolabs.wrangler alias wrangler
40
+ }
41
+ ```
42
+
43
+ Then `wrangler:children()`, `wrangler:channels(["myapp", "app"])`, `wrangler:createChannel(...)`, and so on. Shared functions can also be queried from outside the pico, on a channel whose policy allows them.
44
+
45
+ The guides explain how the pieces fit together. The API reference pages list every event and function each ruleset supports, generated from the rulesets' own doc comments.
46
+
47
+ Wrangler and the engine know nothing about any particular application. Frameworks such as Manifold build on Wrangler to give a mesh of picos its own vocabulary.