pico-engine 1.6.2 → 1.8.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 (107) hide show
  1. package/README.md +117 -14
  2. package/dist/RulesetRegistryLoaderFs.js +24 -8
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/bundledKrl.js +129 -11
  6. package/dist/channelIdentityPolicy.js +22 -0
  7. package/dist/cli.js +105 -46
  8. package/dist/engineConfig.js +280 -0
  9. package/dist/identity/IdentityService.js +90 -0
  10. package/dist/identity/crossPico.js +106 -30
  11. package/dist/identity/didoModule.js +80 -18
  12. package/dist/identity/establishSubscription.js +2 -2
  13. package/dist/identity/identityPortable.js +92 -0
  14. package/dist/identity/index.js +10 -1
  15. package/dist/identity/localPeerReconcile.js +65 -0
  16. package/dist/identity/peerDid4.js +175 -0
  17. package/dist/identity/peerDid4Create.js +90 -0
  18. package/dist/identity/portableExportPrepare.js +196 -0
  19. package/dist/identity/portableMove.js +87 -0
  20. package/dist/identity/skyIntro.js +10 -4
  21. package/dist/identity/skyProtocol.js +26 -1
  22. package/dist/identity/skyRotation.js +121 -0
  23. package/dist/identity/store.js +5 -1
  24. package/dist/identity/subscriptionEntSync.js +72 -0
  25. package/dist/identity/veramoDidComm.js +41 -2
  26. package/dist/identity/webvh.js +4 -2
  27. package/dist/identity/webvhRelocation.js +115 -0
  28. package/dist/index.js +127 -34
  29. package/dist/levelDb.js +102 -0
  30. package/dist/logging.js +47 -8
  31. package/dist/oauth/OAuthService.js +12 -5
  32. package/dist/oauth/channelEligibility.js +7 -1
  33. package/dist/oauth/index.js +3 -1
  34. package/dist/policyConfigFromJson.js +112 -0
  35. package/dist/runMcp.js +27 -0
  36. package/dist/server.js +95 -24
  37. package/dist/subtreeWrangler.js +180 -0
  38. package/dist/uiChannelPolicies.js +16 -0
  39. package/krl/io.picolabs.oauth.krl +51 -5
  40. package/krl/io.picolabs.pds.krl +131 -10
  41. package/krl/io.picolabs.pico-engine-ui.krl +219 -22
  42. package/krl/io.picolabs.portable_subtree.krl +97 -0
  43. package/krl/io.picolabs.subscription.krl +226 -72
  44. package/krl/io.picolabs.wrangler.krl +300 -58
  45. package/mcp/devResources.js +118 -0
  46. package/mcp/devTools.js +351 -0
  47. package/mcp/engineClient.js +133 -0
  48. package/mcp/meshHttp.js +137 -0
  49. package/mcp/meshTools.js +189 -0
  50. package/mcp/runStdio.js +34 -0
  51. package/mcp/schemaToZod.js +56 -0
  52. package/package.json +22 -8
  53. package/public/docs/_sidebar.md +2 -1
  54. package/public/docs/llms-full.txt +479 -0
  55. package/public/docs/llms.txt +37 -0
  56. package/public/docs/openapi.yaml +78 -0
  57. package/public/docs/pico-engine.md +235 -4
  58. package/public/docs/pico-overview.md +117 -0
  59. package/public/docs/pico.md +3 -1
  60. package/public/docs/rulesets/README.md +25 -0
  61. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  62. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  63. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  64. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  65. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  66. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  67. package/public/pico-engine-ui.css +1 -1
  68. package/public/pico-engine-ui.js +28 -26
  69. package/src/RulesetRegistryLoaderFs.ts +43 -11
  70. package/src/auth/cookies.ts +34 -0
  71. package/src/auth/index.ts +7 -0
  72. package/src/bundledKrl.ts +150 -12
  73. package/src/channelIdentityPolicy.ts +29 -0
  74. package/src/cli.ts +98 -40
  75. package/src/engineConfig.ts +345 -0
  76. package/src/identity/IdentityService.ts +189 -1
  77. package/src/identity/crossPico.ts +161 -41
  78. package/src/identity/didoModule.ts +140 -23
  79. package/src/identity/establishSubscription.ts +2 -2
  80. package/src/identity/identityPortable.ts +153 -0
  81. package/src/identity/index.ts +14 -0
  82. package/src/identity/localPeerReconcile.ts +97 -0
  83. package/src/identity/peerDid4.ts +197 -0
  84. package/src/identity/peerDid4Create.ts +121 -0
  85. package/src/identity/portableExportPrepare.ts +302 -0
  86. package/src/identity/portableMove.ts +193 -0
  87. package/src/identity/skyIntro.ts +16 -12
  88. package/src/identity/skyProtocol.ts +46 -0
  89. package/src/identity/skyRotation.ts +211 -0
  90. package/src/identity/store.ts +5 -1
  91. package/src/identity/subscriptionEntSync.ts +97 -0
  92. package/src/identity/veramoDidComm.ts +52 -2
  93. package/src/identity/webvh.ts +4 -4
  94. package/src/identity/webvhRelocation.ts +167 -0
  95. package/src/index.ts +179 -39
  96. package/src/levelDb.ts +122 -0
  97. package/src/logging.ts +63 -11
  98. package/src/oauth/OAuthService.ts +20 -6
  99. package/src/oauth/channelEligibility.ts +9 -0
  100. package/src/oauth/index.ts +7 -1
  101. package/src/policyConfigFromJson.ts +131 -0
  102. package/src/runMcp.ts +30 -0
  103. package/src/server.ts +133 -27
  104. package/src/subtreeWrangler.ts +278 -0
  105. package/src/uiChannelPolicies.ts +16 -0
  106. package/krl/io.picolabs.did-o.krl +0 -349
  107. package/krl/test/didtestdid.krl +0 -78
@@ -0,0 +1,327 @@
1
+ # io.picolabs.pds
2
+
3
+ Pico Data Services (PDS), a common data base structure for all rulesets to use.
4
+
5
+ *Version draft. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
6
+
7
+ **Operations:** [pds:new_data_available](#pdsnew_data_available) · [pds:updated_data_available](#pdsupdated_data_available) · [pds:remove_old_data](#pdsremove_old_data) · [pds:remove_namespace](#pdsremove_namespace) · [pds:map_item](#pdsmap_item) · [pds:updated_profile](#pdsupdated_profile) · [pds:add_settings](#pdsadd_settings)
8
+ **Queries:** [items](#itemsnamespace-key--map) · [get_keys](#get_keysnamespace--array) · [profile](#profilekey--map) · [settings](#settingsrid-key-detail--map) · [get_config_value](#get_config_valuesetkey--any) · [get_setting_data_value](#get_setting_data_valuesetrid-setkey--any) · [config_value](#config_valuesetkey--any) · [settings_names](#settings_names--array) · [getChannelEci](#getchanneleci--string)
9
+
10
+ ## Operations
11
+
12
+ Events you can send to a pico with this ruleset installed. Whether an operation acts, and what it emits, depends on its condition and the pico's state when the event arrives.
13
+
14
+ ### `pds:new_data_available`
15
+
16
+ Store one value in the general data under namespace and key, replacing any existing value. Raises pds:data_added.
17
+
18
+ **Send:** `pds:new_data_available`
19
+ **Rule:** `add_item`
20
+
21
+ | Attribute | Type | Required | Description |
22
+ |-----------|------|----------|-------------|
23
+ | `namespace` | String | yes | namespace, e.g. your app's name |
24
+ | `key` | String | yes | |
25
+ | `value` | Any | yes | value to store |
26
+
27
+ **Examples:**
28
+
29
+ - **store a value:** `{"namespace":"<app>","key":"<key>","value":"<value>"}`
30
+
31
+ **Acts when:** always, once selected
32
+
33
+ **May emit** (possible, not guaranteed):
34
+
35
+ - raises `pds:data_added` on this pico — always
36
+
37
+ <details><summary>Select expression</summary>
38
+
39
+ ```krl
40
+ select when pds new_data_available
41
+ ```
42
+
43
+ </details>
44
+
45
+ ### `pds:updated_data_available`
46
+
47
+ Merge fields into a stored map: each entry of value is written under namespace / key / field, leaving other fields alone. Raises pds:data_updated once per field.
48
+
49
+ **Send:** `pds:updated_data_available`
50
+ **Rule:** `update_item`
51
+
52
+ | Attribute | Type | Required | Description |
53
+ |-----------|------|----------|-------------|
54
+ | `namespace` | String | yes | |
55
+ | `key` | String | yes | |
56
+ | `value` | Map | yes | fields to set on the stored map |
57
+
58
+ **Examples:**
59
+
60
+ - **set fields:** `{"namespace":"<app>","key":"<key>","value":{"<field>":"<value>"}}`
61
+
62
+ **Acts when:** always, once selected
63
+
64
+ **May emit** (possible, not guaranteed):
65
+
66
+ - raises `pds:data_updated` on this pico — always
67
+
68
+ <details><summary>Select expression</summary>
69
+
70
+ ```krl
71
+ select when pds updated_data_available
72
+ ```
73
+
74
+ </details>
75
+
76
+ ### `pds:remove_old_data`
77
+
78
+ Delete one key from a namespace of the general data. Raises pds:data_deleted.
79
+
80
+ **Send:** `pds:remove_old_data`
81
+ **Rule:** `remove_item`
82
+
83
+ | Attribute | Type | Required | Description |
84
+ |-----------|------|----------|-------------|
85
+ | `namespace` | String | yes | |
86
+ | `key` | String | yes | |
87
+
88
+ **Acts when:** always, once selected
89
+
90
+ **May emit** (possible, not guaranteed):
91
+
92
+ - raises `pds:data_deleted` on this pico — always
93
+
94
+ <details><summary>Select expression</summary>
95
+
96
+ ```krl
97
+ select when pds remove_old_data
98
+ ```
99
+
100
+ </details>
101
+
102
+ ### `pds:remove_namespace`
103
+
104
+ Delete a whole namespace of the general data. Raises pds:namespace_deleted.
105
+
106
+ **Send:** `pds:remove_namespace`
107
+ **Rule:** `remove_namespace`
108
+
109
+ | Attribute | Type | Required | Description |
110
+ |-----------|------|----------|-------------|
111
+ | `namespace` | String | yes | |
112
+
113
+ **Acts when:** always, once selected
114
+
115
+ **May emit** (possible, not guaranteed):
116
+
117
+ - raises `pds:namespace_deleted` on this pico — always
118
+
119
+ <details><summary>Select expression</summary>
120
+
121
+ ```krl
122
+ select when pds remove_namespace
123
+ ```
124
+
125
+ </details>
126
+
127
+ ### `pds:map_item`
128
+
129
+ Replace an entire namespace of the general data with a map. Raises pds:new_map_added.
130
+
131
+ **Send:** `pds:map_item`
132
+ **Rule:** `itemed_mapped`
133
+
134
+ | Attribute | Type | Required | Description |
135
+ |-----------|------|----------|-------------|
136
+ | `namespace` | String | yes | |
137
+ | `mapvalues` | String | yes | the new namespace contents, as a JSON-encoded map |
138
+
139
+ **Examples:**
140
+
141
+ - **replace namespace:** `{"namespace":"<app>","mapvalues":"{\"<key>\": \"<value>\"}"}`
142
+
143
+ **Acts when:** always, once selected
144
+
145
+ **May emit** (possible, not guaranteed):
146
+
147
+ - raises `pds:new_map_added` on this pico — always
148
+
149
+ <details><summary>Select expression</summary>
150
+
151
+ ```krl
152
+ select when pds map_item
153
+ ```
154
+
155
+ </details>
156
+
157
+ ### `pds:updated_profile`
158
+
159
+ Update this pico's profile. Send only the fields to change; fields not sent keep their current values. _created is set on the first update and _modified on every update. Raises pds:profile_updated with _status "success", or "failure" when no fields were sent.
160
+
161
+ **Send:** `pds:updated_profile`
162
+ **Rule:** `update_profile`
163
+
164
+ | Attribute | Type | Required | Description |
165
+ |-----------|------|----------|-------------|
166
+ | `name` | String | no | display name |
167
+ | `description` | String | no | |
168
+ | `photo` | String | no | image URL or data: URI |
169
+ | `email` | String | no | |
170
+ | `phone` | String | no | |
171
+
172
+ **Examples:**
173
+
174
+ - **rename:** `{"name":"<name>"}`
175
+ - **contact info:** `{"email":"<email>","phone":"<phone>"}`
176
+
177
+ **Acts when:** `newly_constructed_profile != "nothing to update"`
178
+
179
+ **May emit** (possible, not guaranteed):
180
+
181
+ - raises `pds:profile_updated` on this pico — when it acts
182
+ - raises `pds:profile_updated` on this pico — when it doesn't act
183
+
184
+ <details><summary>Select expression</summary>
185
+
186
+ ```krl
187
+ select when pds updated_profile
188
+ ```
189
+
190
+ </details>
191
+
192
+ ### `pds:add_settings`
193
+
194
+ Create or update a ruleset's settings record, and optionally set one data value in it. Raises pds:settings_added.
195
+
196
+ **Send:** `pds:add_settings`
197
+ **Rule:** `settings_added`
198
+
199
+ | Attribute | Type | Required | Description |
200
+ |-----------|------|----------|-------------|
201
+ | `keyed_rid` | String | yes | ruleset id the settings belong to |
202
+ | `name` | String | yes | display name for the settings |
203
+ | `schema` | Array | no | settings schema, stored as given |
204
+ | `data_key` | String | no | data key to set |
205
+ | `value` | Any | no | value for data_key |
206
+
207
+ **Examples:**
208
+
209
+ - **register settings:** `{"keyed_rid":"<rid>","name":"<display name>"}`
210
+ - **set one value:** `{"keyed_rid":"<rid>","name":"<display name>","data_key":"<key>","value":"<value>"}`
211
+
212
+ **Acts when:** always, once selected
213
+
214
+ **May emit** (possible, not guaranteed):
215
+
216
+ - raises `pds:settings_added` on this pico — always
217
+
218
+ <details><summary>Select expression</summary>
219
+
220
+ ```krl
221
+ select when pds add_settings
222
+ ```
223
+
224
+ </details>
225
+
226
+ ## Queries
227
+
228
+ ### `items(namespace?, key?)` → Map
229
+
230
+ Read general (namespaced) data. With no namespace, returns all of it; with a namespace, that namespace's map; with both, one value. status is "failed" when no namespace is given (the data is still returned).
231
+
232
+ | Parameter | Type | Required | Default | Description |
233
+ |-----------|------|----------|---------|-------------|
234
+ | `namespace` | String | no | | namespace to read; omit for everything |
235
+ | `key` | String | no | | key within the namespace; omit for the whole namespace |
236
+
237
+ **Examples:**
238
+
239
+ - **one namespace:** `{"namespace":"<app>"}`
240
+ - **one value:** `{"namespace":"<app>","key":"<key>"}`
241
+
242
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/items?namespace=…&key=…`, or `<alias>:items(namespace?, key?)` from KRL with `use module io.picolabs.pds alias <alias>`
243
+
244
+ ### `get_keys(namespace)` → Array
245
+
246
+ Keys stored in one namespace of the general data.
247
+
248
+ | Parameter | Type | Required | Default | Description |
249
+ |-----------|------|----------|---------|-------------|
250
+ | `namespace` | String | yes | | |
251
+
252
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_keys?namespace=…`, or `<alias>:get_keys(namespace)` from KRL with `use module io.picolabs.pds alias <alias>`
253
+
254
+ ### `profile(key?)` → Map
255
+
256
+ This pico's profile: name, description, photo, email, phone, and the _created / _modified timestamps. With a key, just that field.
257
+
258
+ | Parameter | Type | Required | Default | Description |
259
+ |-----------|------|----------|---------|-------------|
260
+ | `key` | String | no | | profile field to read; omit for the whole profile |
261
+
262
+ **Examples:**
263
+
264
+ - **whole profile:** `{}`
265
+ - **name only:** `{"key":"name"}`
266
+
267
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/profile?key=…`, or `<alias>:profile(key?)` from KRL with `use module io.picolabs.pds alias <alias>`
268
+
269
+ ### `settings(Rid?, Key?, detail?)` → Map
270
+
271
+ Read per-ruleset settings. No arguments: all settings. Rid: that ruleset's settings record ({ name, rid, data, schema }). Rid and Key: one field of the record. Rid, Key, and detail: the value of data key `detail` (Key is ignored).
272
+
273
+ | Parameter | Type | Required | Default | Description |
274
+ |-----------|------|----------|---------|-------------|
275
+ | `Rid` | String | no | | ruleset id whose settings to read |
276
+ | `Key` | String | no | | field of the settings record (name, rid, data, schema) |
277
+ | `detail` | String | no | | key within the record's data map |
278
+
279
+ **Examples:**
280
+
281
+ - **one ruleset:** `{"Rid":"<rid>"}`
282
+ - **one data value:** `{"Rid":"<rid>","Key":"data","detail":"<key>"}`
283
+
284
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/settings?Rid=…&Key=…&detail=…`, or `<alias>:settings(Rid?, Key?, detail?)` from KRL with `use module io.picolabs.pds alias <alias>`
285
+
286
+ ### `get_config_value(setKey)` → Any
287
+
288
+ Same as config_value: a value from the calling ruleset's own settings data, for use as a module function.
289
+
290
+ | Parameter | Type | Required | Default | Description |
291
+ |-----------|------|----------|---------|-------------|
292
+ | `setKey` | String | yes | | data key |
293
+
294
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_config_value?setKey=…`, or `<alias>:get_config_value(setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
295
+
296
+ ### `get_setting_data_value(setRID, setKey)` → Any
297
+
298
+ One configuration value from a ruleset's settings data.
299
+
300
+ | Parameter | Type | Required | Default | Description |
301
+ |-----------|------|----------|---------|-------------|
302
+ | `setRID` | String | yes | | ruleset id |
303
+ | `setKey` | String | yes | | data key |
304
+
305
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/get_setting_data_value?setRID=…&setKey=…`, or `<alias>:get_setting_data_value(setRID, setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
306
+
307
+ ### `config_value(setKey)` → Any
308
+
309
+ One configuration value from the calling ruleset's own settings data. Meant to be used as a module function (use module io.picolabs.pds): the ruleset is the caller's, from meta:callingRID().
310
+
311
+ | Parameter | Type | Required | Default | Description |
312
+ |-----------|------|----------|---------|-------------|
313
+ | `setKey` | String | yes | | data key |
314
+
315
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/config_value?setKey=…`, or `<alias>:config_value(setKey)` from KRL with `use module io.picolabs.pds alias <alias>`
316
+
317
+ ### `settings_names()` → Array
318
+
319
+ Rulesets that have stored settings here, with their display names.
320
+
321
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/settings_names`, or `<alias>:settings_names()` from KRL with `use module io.picolabs.pds alias <alias>`
322
+
323
+ ### `getChannelEci()` → String
324
+
325
+ The ECI of this pico's pds channel, which allows all pds events and queries. Created when this ruleset is installed.
326
+
327
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pds/getChannelEci`, or `<alias>:getChannelEci()` from KRL with `use module io.picolabs.pds alias <alias>`
@@ -0,0 +1,65 @@
1
+ # io.picolabs.pico-engine-ui
2
+
3
+ This is the only ruleset the pico-engine-ui.js needs to operate
4
+
5
+ *Version 0.0.0. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
6
+
7
+ **Queries:** [box](#box--map) · [uiECI](#uieci--string) · [pico](#pico--map) · [logs](#logs--array) · [testingECI](#testingeci--string) · [testingHistory](#testinghistoryrid--map) · [testingSaved](#testingsavedrid--map) · [name](#name--string)
8
+
9
+ ## Queries
10
+
11
+ ### `box()` → Map
12
+
13
+ How the developer UI draws this pico: name, color, position, size, and the UI channels of its parent and children.
14
+
15
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/box`, or `<alias>:box()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
16
+
17
+ ### `uiECI()` → String
18
+
19
+ The ECI of this pico's UI channel (tagged engine,ui), used by the developer UI to send engine_ui events and queries to this pico.
20
+
21
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/uiECI`, or `<alias>:uiECI()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
22
+
23
+ ### `pico()` → Map
24
+
25
+ This pico's channels (with their policies) and installed rulesets, plus the UI channels of its parent and children. A quick way to see what a pico is.
26
+
27
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/pico`, or `<alias>:pico()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
28
+
29
+ ### `logs()` → Array
30
+
31
+ Recent activity on this pico, grouped by transaction, newest first: each incoming event or query with the rules it selected, klog output, and errors. The developer UI's own queries are left out.
32
+
33
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/logs`, or `<alias>:logs()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
34
+
35
+ ### `testingECI()` → String
36
+
37
+ The channel the developer UI's Testing tab last selected for sending events and queries to this pico, or null.
38
+
39
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingECI`, or `<alias>:testingECI()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
40
+
41
+ ### `testingHistory(rid?)` → Map
42
+
43
+ Recent Testing-tab sends for this pico, keyed by ruleset rid (newest first).
44
+
45
+ | Parameter | Type | Required | Default | Description |
46
+ |-----------|------|----------|---------|-------------|
47
+ | `rid` | String | no | | optional ruleset id; omit for the full map rid → entries |
48
+
49
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingHistory?rid=…`, or `<alias>:testingHistory(rid?)` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
50
+
51
+ ### `testingSaved(rid?)` → Map
52
+
53
+ Named Testing-tab requests kept on this pico, keyed by ruleset rid.
54
+
55
+ | Parameter | Type | Required | Default | Description |
56
+ |-----------|------|----------|---------|-------------|
57
+ | `rid` | String | no | | optional ruleset id; omit for the full map rid → entries |
58
+
59
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/testingSaved?rid=…`, or `<alias>:testingSaved(rid?)` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
60
+
61
+ ### `name()` → String
62
+
63
+ This pico's display name in the developer UI ("Pico" if never set).
64
+
65
+ **Call:** `GET /sky/query/<eci>/io.picolabs.pico-engine-ui/name`, or `<alias>:name()` from KRL with `use module io.picolabs.pico-engine-ui alias <alias>`
@@ -0,0 +1,94 @@
1
+ # io.picolabs.portable_subtree
2
+
3
+ Optional wrangler utility for copying a pico subtree (rulesets, entity state,
4
+ channels, schedules, and Layer 2 identity) to another parent — on the same
5
+ engine or a different one. Not installed by default.
6
+
7
+ Export (install on an ancestor of the subtree to copy):
8
+ portable_subtree:exportSubtree(subtreeRootPicoId, secret)
9
+ → encrypted blob (transfer manually to the destination engine)
10
+
11
+ Inspect a blob before import (same secret):
12
+ portable_subtree:summarizeExportBlob(blob, secret)
13
+
14
+ Import (install on the adopting parent):
15
+ raise portable_subtree event "import"
16
+ attributes { "blob": "...", "secret": "..." }
17
+ → portable_subtree:imported event; read result with portable_subtree:lastImport()
18
+
19
+ The importer must ensure the recipient mesh provides any platform services
20
+ the subtree relied on from ancestors in the donor mesh (e.g. import a
21
+ Manifold app pico under a Manifold parent, not a bare wrangler root).
22
+
23
+ After import, delete the source subtree manually if you no longer need it.
24
+
25
+ *Version draft. Generated from the ruleset's annotations by `krl-schema --format markdown`; edit the `/** */` comments in the source, not this page. Only annotated rules and shared functions appear.*
26
+
27
+ **Operations:** [portable_subtree:import](#portable_subtreeimport)
28
+ **Queries:** [exportSubtree](#exportsubtreesubtreerootpicoid-secret--string) · [lastImport](#lastimport--map) · [summarizeExportBlob](#summarizeexportblobblob-secret--map)
29
+
30
+ ## Operations
31
+
32
+ Events you can send to a pico with this ruleset installed. Whether an operation acts, and what it emits, depends on its condition and the pico's state when the event arrives.
33
+
34
+ ### `portable_subtree:import`
35
+
36
+ Import an exported subtree as a child of this pico. Rulesets, entity state, channels, schedules, and identity are restored, and Layer 2 relationships are relocated so they survive the move. The result is stored for lastImport() and raised as portable_subtree:imported. This pico must provide any platform services the subtree relied on in its old mesh (e.g. import a Manifold app pico under a Manifold parent). The source subtree is not deleted.
37
+
38
+ **Send:** `portable_subtree:import`
39
+ **Rule:** `import_subtree`
40
+
41
+ | Attribute | Type | Required | Description |
42
+ |-----------|------|----------|-------------|
43
+ | `blob` | String | yes | export blob from exportSubtree |
44
+ | `secret` | String | yes | the secret used to export it |
45
+ | `renewIngress` | Boolean | no | mint a fresh DIDComm ingress channel when relocating each pico's did:webvh (default true) |
46
+ | `bootstrapDisplayName` | String | no | display name for the imported root |
47
+
48
+ **Examples:**
49
+
50
+ - **import:** `{"blob":"<blob from exportSubtree>","secret":"<secret>"}`
51
+
52
+ **Acts when:** always, once selected
53
+
54
+ **May emit** (possible, not guaranteed):
55
+
56
+ - raises `portable_subtree:imported` on this pico — when it acts
57
+
58
+ <details><summary>Select expression</summary>
59
+
60
+ ```krl
61
+ select when portable_subtree import
62
+ ```
63
+
64
+ </details>
65
+
66
+ ## Queries
67
+
68
+ ### `exportSubtree(subtreeRootPicoId, secret)` → String
69
+
70
+ Export a descendant subtree (or this pico itself) as an encrypted blob: rulesets, entity state, channels, schedules, and Layer 2 identity. Read-only; the source subtree is untouched. Transfer the blob to the adopting parent and send it portable_subtree:import there with the same secret.
71
+
72
+ | Parameter | Type | Required | Default | Description |
73
+ |-----------|------|----------|---------|-------------|
74
+ | `subtreeRootPicoId` | String | yes | | pico id of the subtree root; this pico's own id exports this pico |
75
+ | `secret` | String | yes | | encryption secret; the importer needs the same one |
76
+
77
+ **Call:** `GET /sky/query/<eci>/io.picolabs.portable_subtree/exportSubtree?subtreeRootPicoId=…&secret=…`, or `<alias>:exportSubtree(subtreeRootPicoId, secret)` from KRL with `use module io.picolabs.portable_subtree alias <alias>`
78
+
79
+ ### `lastImport()` → Map
80
+
81
+ Result of the most recent portable_subtree:import on this pico (the same attrs as the portable_subtree:imported event), or null if none.
82
+
83
+ **Call:** `GET /sky/query/<eci>/io.picolabs.portable_subtree/lastImport`, or `<alias>:lastImport()` from KRL with `use module io.picolabs.portable_subtree alias <alias>`
84
+
85
+ ### `summarizeExportBlob(blob, secret)` → Map
86
+
87
+ Inspect an export blob before importing it: subtree root name, relationship count, rulesets with entity state, and similar. Read-only.
88
+
89
+ | Parameter | Type | Required | Default | Description |
90
+ |-----------|------|----------|---------|-------------|
91
+ | `blob` | String | yes | | export blob from exportSubtree |
92
+ | `secret` | String | yes | | the secret used to export it |
93
+
94
+ **Call:** `GET /sky/query/<eci>/io.picolabs.portable_subtree/summarizeExportBlob?blob=…&secret=…`, or `<alias>:summarizeExportBlob(blob, secret)` from KRL with `use module io.picolabs.portable_subtree alias <alias>`