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,470 @@
1
+ # Pico-Based Systems
2
+
3
+ Solving a problem with picos usually means building a **system** of picos that cooperate. This lesson is about the simplest way picos are related: **parent and child**. You'll create children by hand and from KRL, give each one a ruleset, keep a directory of them, and delete them.
4
+
5
+ The running example is a class registration system. A *Section Collection* pico keeps one child pico per section of a course. Later lessons add students and connect them to sections.
6
+
7
+ ## Objectives
8
+
9
+ When you finish you will be able to:
10
+
11
+ - explain the root pico, parents, children, and family channels
12
+ - create and delete child picos in the developer UI
13
+ - create and delete children from a rule with `wrangler:new_child_request` and `wrangler:child_deletion_request`
14
+ - install a ruleset in a child with `wrangler:install_ruleset_request` and react to `wrangler:ruleset_installed`
15
+ - keep a map of section id to the child's ECI, and say why two rules select the same event
16
+ - explain why a pico needs no locks
17
+ - list children with `wrangler:children()` and query one with `wrangler:picoQuery`
18
+
19
+ **Before you begin**, finish [Pico State](/lessons/pico-state). It helps to have read [Pico overview](/pico-overview) and the [Wrangler](/wrangler/) page. The [wrangler ruleset](/wrangler/wrangler) documents every event and function used here.
20
+
21
+ ## Children
22
+
23
+ When your engine starts for the first time it creates one pico, the **root pico**. Every other pico has exactly one **parent**, the pico that created it. A pico can have as many children as it likes, and children can have children, so picos form a tree.
24
+
25
+ A parent and child are connected by **family channels**: the parent has a channel to the child, and the child has one to the parent. A pico uses the family channel to its parent for `wrangler:parent_eci()`, and a parent's `wrangler:children()` lists the family channel (`eci`) to each child. Only the parent can use its channel to the child, and Wrangler, the "pico operating system" ruleset that comes with every pico, manages both.
26
+
27
+ ## Create children in the UI
28
+
29
+ <img src="/lessons/_media/21168151-system-about.png" alt="The root pico About tab before adding a child" width="50%">
30
+
31
+ Open your root pico and click its **About** tab. Under **Children**, type a name and choose a color, then click the add button. Call the new pico "Registration". The About tab lists the new child with its ECI. Click the link to visit it. Notice that it has a **Parent** link and no children yet.
32
+
33
+ <img src="/lessons/_media/21168151-system-about3.png" alt="A child pico's About tab showing its Parent link and no children" width="50%">
34
+
35
+ Create a second child of the root, "Section Collection", with a different color.
36
+
37
+ <img src="/lessons/_media/21168151-system-about2.png" alt="The About tab of the root pico, listing the Registration child with its ECI and a form to add another" width="50%">
38
+
39
+ Click **Close** to see the layout: two picos connected to the root by their parent-child links. Drag them around. The layout is saved.
40
+
41
+ <img src="/lessons/_media/21168151-system-view.png" alt="The pico layout: the root pico connected to the Registration and Section Collection picos" width="50%">
42
+
43
+ <img src="/lessons/_media/21168151-reglayout.png" alt="Diagram of the registration system pico layout" width="50%">
44
+
45
+ ## Delete children in the UI
46
+
47
+ Beside each child on the About tab is a **delete** link. Create a throwaway child inside one of the picos and delete it.
48
+
49
+ Deleting is permanent. Its channels, rulesets, state, and relationships are gone, and so are any picos below it. A parent is the only pico that can delete a child. The root pico can't be deleted.
50
+
51
+ ## Create children from a rule
52
+
53
+ Picos create picos. The running example needs two more kinds, one pico for each section and one for each student, and they'll be made on demand. BYU teaches thousands of sections a semester; nobody is going to click add that many times.
54
+
55
+ We'll write a ruleset for the Section Collection pico. It's a directory: other picos, or the outside world (a class management system, say), tell it that a section needs a pico. It creates the pico and records it. Here's the plan:
56
+
57
+ ```
58
+ root pico
59
+ ├── Registration pico
60
+ └── Section Collection pico
61
+ ├── Section CS462-1 pico
62
+ └── Section CS462-2 pico
63
+ ```
64
+
65
+ Create `app_section_collection.krl`. Here is the part that asks for a child:
66
+
67
+ ```krl
68
+ rule section_needed {
69
+ select when section needed
70
+ pre {
71
+ section_id = event:attr("section_id")
72
+ exists = ent:sections.defaultsTo({}) >< section_id
73
+ }
74
+ if not exists then noop()
75
+ fired {
76
+ ent:sections{section_id} := {}
77
+ raise wrangler event "new_child_request" attributes {
78
+ "name": nameFromID(section_id),
79
+ "backgroundColor": "#ff69b4",
80
+ "section_id": section_id
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
86
+ A tour of the rule:
87
+
88
+ - It's selected by events in the `section` domain of type `needed`.
89
+ - The prelude names two values. `section_id` is the event attribute of that name. `exists` is true if `ent:sections` already has that id as a key. `><` is the membership operator, and for a map it tests keys.
90
+ - The condition is `not exists`. `noop()` is an action that does nothing, so the rule has a condition to fire on and a postlude to run.
91
+ - The postlude runs when the rule fired, that is, when the section is new. It records the section in the map, and raises `wrangler:new_child_request`.
92
+
93
+ `raise` puts an event on this pico's own queue, and the Wrangler ruleset, which is installed on every pico, handles it. That's the same event the developer UI sends when you click add. Wrangler creates the child, installs the developer UI ruleset and itself in it, and tells your pico when it's done. The `name` and `backgroundColor` are for the UI. Any other attributes, such as `section_id`, are passed along to the new pico and come back to the parent with Wrangler's events, which is how a parent tells its children apart. The function `nameFromID` is in the `global` block:
94
+
95
+ ```krl
96
+ nameFromID = function(section_id) {
97
+ "Section " + section_id + " Pico"
98
+ }
99
+ ```
100
+
101
+ Share it, and `sections` (below), in the `meta` block with `shares`. The full ruleset is at the end of this lesson. Install it in the Section Collection pico on the **Rulesets** tab.
102
+
103
+ ### Make a section pico
104
+
105
+ On the Section Collection pico's **Testing** tab, `section:needed` appears as a form. (Rules with a documentation comment, `@attr`, and `@example` show up there.) Enter a section id such as `CS462-1` and click the button. Close the pico and its tabs, and a new pink child is there.
106
+
107
+ <img src="/lessons/_media/21168151-system-testing.png" alt="The Testing tab of the Section Collection pico with the section:needed form" width="50%">
108
+
109
+ <img src="/lessons/_media/21168151-system-view2.png" alt="The layout after the event: a new pink section pico under the Section Collection pico" width="50%">
110
+
111
+ ### Why two rules?
112
+
113
+ There are two cases when a section is needed: its pico already exists, or it has to be created. We write a rule for each, and both select `section:needed`:
114
+
115
+ ```krl
116
+ rule section_already_exists {
117
+ select when section needed
118
+ pre {
119
+ section_id = event:attr("section_id")
120
+ exists = ent:sections.defaultsTo({}) >< section_id
121
+ }
122
+ if exists then
123
+ send_directive("section_ready", {"section_id": section_id})
124
+ }
125
+ ```
126
+
127
+ Every rule selected by an event runs, in the order they appear in the ruleset. The `section_needed` rule above does its work only when the section is new, and this one only when it isn't, so exactly one of them acts. Put `section_already_exists` first. If `section_needed` ran first, it would record the new section and `section_already_exists` would then find it and say it was ready.
128
+
129
+ The directive tells the sender what happened: `section_ready` when there was nothing to do.
130
+
131
+ ### Start from an empty map
132
+
133
+ `ent:sections` is the map of sections, and it's the directory. To start over, add a rule:
134
+
135
+ ```krl
136
+ rule initialize_sections {
137
+ select when section needs_initialization
138
+ always {
139
+ ent:sections := {}
140
+ }
141
+ }
142
+ ```
143
+
144
+ and share a function that shows it:
145
+
146
+ ```krl
147
+ sections = function() {
148
+ ent:sections
149
+ }
150
+ ```
151
+
152
+ ## What about race conditions?
153
+
154
+ You may have noticed this pattern:
155
+
156
+ ```
157
+ exists = ent:sections >< section_id // is this id in the map?
158
+ if not exists // if not,
159
+ ent:sections{section_id} := {} // add it
160
+ ```
161
+
162
+ It looks like a critical section that needs a lock. What if two events for the same section arrive at the same moment?
163
+
164
+ It's taken care of. When an event selects a rule, that rule runs to completion before the pico looks at any other event. The check and the update happen as one atomic step, and only then is the next event taken from the queue. A pico encapsulates its state and also synchronizes access to it. We say picos are **single-threaded**, even though the engine is concurrent: many picos can be handling events at the same time, but no pico handles two at once. Picos need no locks.
165
+
166
+ One more detail, because the atomic step is one *event*, not a whole *task*. Creating a child takes several events. If the rule only recorded the section when the child appeared, a second `section:needed` for the same id could arrive before that, find nothing, and request a second child. That's why `section_needed` writes `ent:sections{section_id} := {}` at once, as a placeholder, in the same step as the check. The ECI is filled in later.
167
+
168
+ ## Record where each child is
169
+
170
+ To talk to a section pico, the collection needs its ECI. When Wrangler has created the child, it raises `wrangler:new_child_created` in the parent, with the child's family channel `eci` and its `uiEci`, plus the attributes you passed in. Store the ECI under the section id:
171
+
172
+ ```krl
173
+ rule store_new_section {
174
+ select when wrangler new_child_created where event:attr("section_id")
175
+ pre {
176
+ section_id = event:attr("section_id")
177
+ }
178
+ always {
179
+ ent:sections{[section_id, "eci"]} := event:attr("eci")
180
+ }
181
+ }
182
+ ```
183
+
184
+ The `where` clause makes the rule apply only to children this ruleset asked for. The path assignment `ent:sections{[section_id, "eci"]} := …` sets one part of one entry. `sections()` now looks like this:
185
+
186
+ ```json
187
+ {
188
+ "CS462-1": { "eci": "cm0a8w4ks0004m8ys0p1e5k2r" },
189
+ "CS462-2": { "eci": "cm0a8w9sd0008m8ysg2l73c1d" }
190
+ }
191
+ ```
192
+
193
+ (ECIs vary. Yours will look different.) To clear out earlier experiments, delete the old children on the About tab and raise `section:needs_initialization`.
194
+
195
+ <img src="/lessons/_media/21168151-system-testing2.png" alt="The Testing tab querying sections, showing persisted section entries with ECIs" width="50%">
196
+
197
+ > **Note:** Don't use the old chained form `ent:sections{section_id}{"eci"} := …`. It doesn't parse. Use a composite path, `ent:sections{[section_id, "eci"]}`.
198
+
199
+ ## List the children
200
+
201
+ Add `use module io.picolabs.wrangler alias wrangler` to the `meta` block. Then `wrangler:children()` returns an array with one map per child:
202
+
203
+ ```json
204
+ [
205
+ { "eci": "cm0a8w4ks0004m8ys0p1e5k2r", "name": "Section CS462-1 Pico", "parent_eci": "..." }
206
+ ]
207
+ ```
208
+
209
+ Wrangler functions are available inside your ruleset after `use module`, but to call one from outside the pico you must wrap it in a shared function:
210
+
211
+ ```krl
212
+ showChildren = function() {
213
+ wrangler:children()
214
+ }
215
+ ```
216
+
217
+ Share it, and the Testing tab shows `showChildren` and `sections` as queries.
218
+
219
+ ## Query a child
220
+
221
+ You'll often need to ask a child something. In the [Events and Queries](/lessons/events-and-queries) lesson you queried a pico over HTTP. Don't do that from KRL: use `wrangler:picoQuery(eci, rid, name, args)`. On the same engine it calls the other pico directly, and it can use a family channel, which HTTP can't. It returns the function's value, or a map with `error` if the call failed.
222
+
223
+ ```krl
224
+ sectionIdOf = function(section_id) {
225
+ eci = ent:sections{[section_id, "eci"]}
226
+ eci => wrangler:picoQuery(eci, "app_section", "sectionId", {}) | null
227
+ }
228
+ ```
229
+
230
+ This asks a section pico which section it thinks it is, by calling the shared function `sectionId` of the ruleset `app_section`, which we'll write next. In a rule you would check the answer with `if answer{"error"}.isnull() then …`. A pico can't query itself, and a query waits for its answer, so avoid two picos that query each other at the same time. See [Querying another pico](/developing/querying-another-pico).
231
+
232
+ ## Install a ruleset in a child
233
+
234
+ Why give a section pico any rulesets? A ruleset is behavior. A pico can be a digital twin of something real, here a section of a course, and its ruleset is what it does with events about that section.
235
+
236
+ Make a ruleset, `app_section.krl`, for the section picos. It can start nearly empty:
237
+
238
+ ```krl
239
+ ruleset app_section {
240
+ meta {
241
+ name "Section"
242
+ shares sectionId
243
+ }
244
+ global {
245
+ sectionId = function() {
246
+ ent:section_id
247
+ }
248
+ }
249
+ }
250
+ ```
251
+
252
+ **By hand.** Visit a section pico's **Rulesets** tab and install it.
253
+
254
+ **From a rule.** The parent asks the child's Wrangler to install it, by sending the child `wrangler:install_ruleset_request`. Wait until the child has finished setting up: when it has, Wrangler sends the parent `wrangler:child_initialized`, with the child's `eci` and the attributes of your request.
255
+
256
+ ```krl
257
+ rule install_section_ruleset {
258
+ select when wrangler child_initialized where event:attr("section_id")
259
+ event:send({
260
+ "eci": event:attr("eci"),
261
+ "domain": "wrangler",
262
+ "type": "install_ruleset_request",
263
+ "attrs": {
264
+ "absoluteURL": meta:rulesetURI,
265
+ "rid": "app_section",
266
+ "section_id": event:attr("section_id")
267
+ }
268
+ })
269
+ }
270
+ ```
271
+
272
+ `event:send` goes in the action block, never in a postlude. It sends the event to the child pico's channel. There are two ways to say what to install. With `url`, Wrangler installs the KRL at that URL. With `absoluteURL` and `rid`, it installs `<rid>.krl` from the same folder as `absoluteURL`. `meta:rulesetURI` is the URL of the ruleset that's running, so `app_section.krl` has to be in the same folder as `app_section_collection.krl`. This works like a relative URL in a web page: the browser resolves `page2.html` against the page it came from, and Wrangler resolves `app_section` against `meta:rulesetURI`.
273
+
274
+ <img src="/lessons/_media/21168151-relativeurl.png" alt="Installing a ruleset using absoluteURL resolved relative to meta:rulesetURI" width="50%">
275
+
276
+ Wrangler fetches and compiles the ruleset, installs it, and then raises `wrangler:ruleset_installed` in the **child**, with `rids` (an array holding the installed rid) and the other attributes of the request. So `section_id` is passed through, without Wrangler looking at it. The new ruleset's first event is `ruleset_installed`, and every ruleset on that pico sees it, so select your own with `where event:attr("rids") >< meta:rid`:
277
+
278
+ ```krl
279
+ rule pico_ruleset_added {
280
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
281
+ always {
282
+ ent:section_id := event:attr("section_id")
283
+ }
284
+ }
285
+ ```
286
+
287
+ Add this rule to `app_section`. Now follow `section_id` the whole way: it starts as an attribute of `section:needed`, goes through `new_child_request` to Wrangler, comes back in `child_initialized`, is sent in `install_ruleset_request`, appears in `ruleset_installed`, and ends up in the child's `ent:section_id`. Create a section and check with `sectionIdOf`.
288
+
289
+ If the ruleset doesn't compile, Wrangler raises `wrangler:ruleset_install_failed` instead, with the compiler's errors. See [The wrangler ruleset](/wrangler/wrangler).
290
+
291
+ ## Delete a child from a rule
292
+
293
+ When the Section Collection learns that a section has gone off-line, it deletes that section's pico. Only the parent can do it, by raising `wrangler:child_deletion_request` with `eci` set to the family channel of the child, the same value you stored in `ent:sections`:
294
+
295
+ ```krl
296
+ rule section_offline {
297
+ select when section offline
298
+ pre {
299
+ section_id = event:attr("section_id")
300
+ eci_to_delete = ent:sections{[section_id, "eci"]}
301
+ }
302
+ if eci_to_delete then
303
+ send_directive("deleting_section", {"section_id": section_id})
304
+ fired {
305
+ raise wrangler event "child_deletion_request" attributes {"eci": eci_to_delete}
306
+ clear ent:sections{section_id}
307
+ }
308
+ }
309
+ ```
310
+
311
+ The directive is the rule's action, and it only happens if the section exists. The postlude asks Wrangler to delete the pico, and clears the section from the map. Wrangler deletes the child and all its descendants, then raises `wrangler:child_deleted` in the parent with the same attributes, in case another rule wants to know. Try it from the Testing tab with `section:offline`.
312
+
313
+ > **Note:** The deletion request takes the child's `eci`. An older form of this event took an `id`. It no longer works, and nothing happens if you use it.
314
+
315
+ A child can also ask for its own deletion by raising `wrangler:ready_for_deletion`. Wrangler passes the request to the parent as a `child_deletion_request`. The [Child pico tasks](/cookbook/child_tasks/) demo does that: each job runs in its own child pico, which reports and then removes itself.
316
+
317
+ ## Put it together
318
+
319
+ The three steps for a child (create it, install its ruleset, learn when it's ready) can run as a chain with no waiting:
320
+
321
+ 1. Your rule raises `wrangler:new_child_request`.
322
+ 2. Wrangler raises `wrangler:new_child_created`. You record the child.
323
+ 3. Wrangler raises `wrangler:child_initialized`. You send `wrangler:install_ruleset_request`.
324
+ 4. Wrangler in the child raises `wrangler:ruleset_installed`. The child's ruleset starts up, and can tell its parent with an event of its own.
325
+
326
+ Each step starts the next. Nothing sleeps or polls, and you don't schedule an event to wait for the child.
327
+
328
+ ## The whole ruleset
329
+
330
+ ```krl
331
+ ruleset app_section_collection {
332
+ meta {
333
+ name "Section collection"
334
+ description "Creates, tracks, and deletes section picos."
335
+ use module io.picolabs.wrangler alias wrangler
336
+ shares sections, showChildren, sectionIdOf
337
+ }
338
+ global {
339
+ nameFromID = function(section_id) {
340
+ "Section " + section_id + " Pico"
341
+ }
342
+
343
+ /**
344
+ * The sections: section_id to { eci }.
345
+ * @returns Map
346
+ */
347
+ sections = function() {
348
+ ent:sections
349
+ }
350
+
351
+ /**
352
+ * This pico's children, from Wrangler.
353
+ * @returns Array of { eci, name, parent_eci }
354
+ */
355
+ showChildren = function() {
356
+ wrangler:children()
357
+ }
358
+
359
+ /**
360
+ * Ask a section pico which section it believes it is.
361
+ * @param section_id String "a section this pico created"
362
+ */
363
+ sectionIdOf = function(section_id) {
364
+ eci = ent:sections{[section_id, "eci"]}
365
+ eci => wrangler:picoQuery(eci, "app_section", "sectionId", {}) | null
366
+ }
367
+ }
368
+
369
+ /**
370
+ * Start over with no sections.
371
+ */
372
+ rule initialize_sections {
373
+ select when section needs_initialization
374
+ always {
375
+ ent:sections := {}
376
+ }
377
+ }
378
+
379
+ /**
380
+ * A section pico is needed. If one exists, say so.
381
+ * @attr section_id String "such as CS462-1"
382
+ * @example "CS 462, section 1" { "section_id": "CS462-1" }
383
+ */
384
+ rule section_already_exists {
385
+ select when section needed
386
+ pre {
387
+ section_id = event:attr("section_id")
388
+ exists = ent:sections.defaultsTo({}) >< section_id
389
+ }
390
+ if exists then
391
+ send_directive("section_ready", {"section_id": section_id})
392
+ }
393
+
394
+ // Same event, other case: no pico for this section yet.
395
+ rule section_needed {
396
+ select when section needed
397
+ pre {
398
+ section_id = event:attr("section_id")
399
+ exists = ent:sections.defaultsTo({}) >< section_id
400
+ }
401
+ if not exists then noop()
402
+ fired {
403
+ ent:sections{section_id} := {}
404
+ raise wrangler event "new_child_request" attributes {
405
+ "name": nameFromID(section_id),
406
+ "backgroundColor": "#ff69b4",
407
+ "section_id": section_id
408
+ }
409
+ }
410
+ }
411
+
412
+ rule store_new_section {
413
+ select when wrangler new_child_created where event:attr("section_id")
414
+ pre {
415
+ section_id = event:attr("section_id")
416
+ }
417
+ always {
418
+ ent:sections{[section_id, "eci"]} := event:attr("eci")
419
+ }
420
+ }
421
+
422
+ rule install_section_ruleset {
423
+ select when wrangler child_initialized where event:attr("section_id")
424
+ event:send({
425
+ "eci": event:attr("eci"),
426
+ "domain": "wrangler",
427
+ "type": "install_ruleset_request",
428
+ "attrs": {
429
+ "absoluteURL": meta:rulesetURI,
430
+ "rid": "app_section",
431
+ "section_id": event:attr("section_id")
432
+ }
433
+ })
434
+ }
435
+
436
+ /**
437
+ * A section has gone off-line: delete its pico.
438
+ * @attr section_id String "a section this pico created"
439
+ * @example "CS 462, section 1" { "section_id": "CS462-1" }
440
+ */
441
+ rule section_offline {
442
+ select when section offline
443
+ pre {
444
+ section_id = event:attr("section_id")
445
+ eci_to_delete = ent:sections{[section_id, "eci"]}
446
+ }
447
+ if eci_to_delete then
448
+ send_directive("deleting_section", {"section_id": section_id})
449
+ fired {
450
+ raise wrangler event "child_deletion_request" attributes {"eci": eci_to_delete}
451
+ clear ent:sections{section_id}
452
+ }
453
+ }
454
+ }
455
+ ```
456
+
457
+ ## Exercises
458
+
459
+ 1. Make `section_needed` accept a `name` for the section as well, and use it in place of `nameFromID`.
460
+ 2. When a section pico finishes installing, have `app_section` tell its parent (`wrangler:parent_eci()`) with an event, and have the collection record that the section is ready.
461
+ 3. Add a function that returns `ent:sections` filtered to the sections whose picos are known (have an `eci`).
462
+ 4. When `wrangler:child_deleted` arrives, remove any entry with that `eci` from `ent:sections` too, in case a child was deleted in the UI.
463
+
464
+ ## Next
465
+
466
+ [Relationships](/lessons/relationships) connects picos that aren't parent and child: students to the sections they take. For another parent and child example you can run, see [Child pico tasks](/cookbook/child_tasks/) and [Wrangler](/wrangler/).
467
+
468
+ ---
469
+
470
+ <small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/21168151) (Pico-Based Systems Lesson, last edited there 2021-02-25), and updated for this engine.</small>