pico-engine 1.6.4 → 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 (98) hide show
  1. package/README.md +13 -8
  2. package/dist/RulesetRegistryLoaderFs.js +14 -2
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/channelIdentityPolicy.js +22 -0
  6. package/dist/cli.js +104 -69
  7. package/dist/engineConfig.js +280 -0
  8. package/dist/identity/IdentityService.js +90 -0
  9. package/dist/identity/crossPico.js +24 -8
  10. package/dist/identity/didoModule.js +80 -18
  11. package/dist/identity/establishSubscription.js +2 -2
  12. package/dist/identity/identityPortable.js +92 -0
  13. package/dist/identity/index.js +10 -1
  14. package/dist/identity/localPeerReconcile.js +65 -0
  15. package/dist/identity/peerDid4.js +175 -0
  16. package/dist/identity/peerDid4Create.js +90 -0
  17. package/dist/identity/portableExportPrepare.js +196 -0
  18. package/dist/identity/portableMove.js +87 -0
  19. package/dist/identity/skyIntro.js +6 -3
  20. package/dist/identity/skyProtocol.js +26 -1
  21. package/dist/identity/skyRotation.js +121 -0
  22. package/dist/identity/store.js +5 -1
  23. package/dist/identity/subscriptionEntSync.js +72 -0
  24. package/dist/identity/veramoDidComm.js +41 -2
  25. package/dist/identity/webvh.js +4 -2
  26. package/dist/identity/webvhRelocation.js +115 -0
  27. package/dist/index.js +82 -22
  28. package/dist/logging.js +8 -12
  29. package/dist/oauth/OAuthService.js +6 -2
  30. package/dist/policyConfigFromJson.js +112 -0
  31. package/dist/runMcp.js +27 -0
  32. package/dist/server.js +56 -24
  33. package/dist/subtreeWrangler.js +180 -0
  34. package/dist/uiChannelPolicies.js +15 -0
  35. package/krl/io.picolabs.oauth.krl +41 -2
  36. package/krl/io.picolabs.pds.krl +131 -10
  37. package/krl/io.picolabs.pico-engine-ui.krl +209 -21
  38. package/krl/io.picolabs.portable_subtree.krl +97 -0
  39. package/krl/io.picolabs.subscription.krl +180 -72
  40. package/krl/io.picolabs.wrangler.krl +296 -57
  41. package/mcp/devResources.js +118 -0
  42. package/mcp/devTools.js +351 -0
  43. package/mcp/engineClient.js +133 -0
  44. package/mcp/meshHttp.js +137 -0
  45. package/mcp/meshTools.js +189 -0
  46. package/mcp/runStdio.js +34 -0
  47. package/mcp/schemaToZod.js +56 -0
  48. package/package.json +20 -8
  49. package/public/docs/_sidebar.md +2 -1
  50. package/public/docs/llms-full.txt +479 -0
  51. package/public/docs/llms.txt +37 -0
  52. package/public/docs/openapi.yaml +78 -0
  53. package/public/docs/pico-engine.md +235 -4
  54. package/public/docs/pico-overview.md +117 -0
  55. package/public/docs/pico.md +3 -1
  56. package/public/docs/rulesets/README.md +25 -0
  57. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  58. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  59. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  60. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  61. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  62. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  63. package/public/pico-engine-ui.css +1 -1
  64. package/public/pico-engine-ui.js +28 -26
  65. package/src/RulesetRegistryLoaderFs.ts +18 -3
  66. package/src/auth/cookies.ts +34 -0
  67. package/src/auth/index.ts +7 -0
  68. package/src/channelIdentityPolicy.ts +29 -0
  69. package/src/cli.ts +68 -37
  70. package/src/engineConfig.ts +345 -0
  71. package/src/identity/IdentityService.ts +189 -1
  72. package/src/identity/crossPico.ts +57 -8
  73. package/src/identity/didoModule.ts +140 -23
  74. package/src/identity/establishSubscription.ts +2 -2
  75. package/src/identity/identityPortable.ts +153 -0
  76. package/src/identity/index.ts +14 -0
  77. package/src/identity/localPeerReconcile.ts +97 -0
  78. package/src/identity/peerDid4.ts +197 -0
  79. package/src/identity/peerDid4Create.ts +121 -0
  80. package/src/identity/portableExportPrepare.ts +302 -0
  81. package/src/identity/portableMove.ts +193 -0
  82. package/src/identity/skyIntro.ts +11 -11
  83. package/src/identity/skyProtocol.ts +46 -0
  84. package/src/identity/skyRotation.ts +211 -0
  85. package/src/identity/store.ts +5 -1
  86. package/src/identity/subscriptionEntSync.ts +97 -0
  87. package/src/identity/veramoDidComm.ts +52 -2
  88. package/src/identity/webvh.ts +4 -4
  89. package/src/identity/webvhRelocation.ts +167 -0
  90. package/src/index.ts +119 -25
  91. package/src/logging.ts +8 -14
  92. package/src/oauth/OAuthService.ts +11 -3
  93. package/src/policyConfigFromJson.ts +131 -0
  94. package/src/runMcp.ts +30 -0
  95. package/src/server.ts +79 -26
  96. package/src/subtreeWrangler.ts +278 -0
  97. package/src/uiChannelPolicies.ts +15 -0
  98. package/krl/io.picolabs.did-o.krl +0 -349
@@ -3,9 +3,14 @@ ruleset io.picolabs.pico-engine-ui {
3
3
  version "0.0.0"
4
4
  name "pico-engine-ui"
5
5
  description "This is the only ruleset the pico-engine-ui.js needs to operate"
6
- shares box, uiECI, pico, logs, testingECI, name, needsStartupLayout
6
+ shares box, uiECI, pico, logs, testingECI, testingHistory, testingSaved, name, needsStartupLayout
7
7
  }
8
8
  global {
9
+ /**
10
+ * The ECI of this pico's UI channel (tagged engine,ui), used by the developer
11
+ * UI to send engine_ui events and queries to this pico.
12
+ * @returns String
13
+ */
9
14
  uiECI = function(){
10
15
  return ctx:channels
11
16
  .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
@@ -23,15 +28,48 @@ ruleset io.picolabs.pico-engine-ui {
23
28
  .map(uiEciForChild)
24
29
  .filter(function(eci){eci})
25
30
  }
31
+ /**
32
+ * The channel the developer UI's Testing tab last selected for sending events
33
+ * and queries to this pico, or null.
34
+ * @returns String
35
+ */
26
36
  testingECI = function(){
27
37
  return ent:testingECI
28
38
  }
39
+ testingHistoryCap = 50
40
+ /**
41
+ * Recent Testing-tab sends for this pico, keyed by ruleset rid (newest first).
42
+ * @param rid String optional "ruleset id; omit for the full map rid → entries"
43
+ * @returns Map or Array
44
+ */
45
+ testingHistory = function(rid = null) {
46
+ rid.isnull() || rid == "" => ent:testing_history.defaultsTo({}) |
47
+ ent:testing_history{rid}.defaultsTo([])
48
+ }
49
+ /**
50
+ * Named Testing-tab requests kept on this pico, keyed by ruleset rid.
51
+ * @param rid String optional ruleset id; omit for the full map rid → entries
52
+ * @returns Map or Array
53
+ */
54
+ testingSaved = function(rid = null) {
55
+ rid.isnull() || rid == "" => ent:testing_saved.defaultsTo({}) |
56
+ ent:testing_saved{rid}.defaultsTo([])
57
+ }
58
+ /**
59
+ * This pico's display name in the developer UI ("Pico" if never set).
60
+ * @returns String
61
+ */
29
62
  name = function(){
30
63
  ent:name || "Pico"
31
64
  }
32
65
  needsStartupLayout = function(){
33
66
  ent:x.isnull() && ent:y.isnull()
34
67
  }
68
+ /**
69
+ * How the developer UI draws this pico: name, color, position, size, and the
70
+ * UI channels of its parent and children.
71
+ * @returns Map "{ eci, parent, children, name, backgroundColor, x, y, width, height }"
72
+ */
35
73
  box = function(){
36
74
  return {
37
75
  "eci": uiECI(),
@@ -41,10 +79,15 @@ ruleset io.picolabs.pico-engine-ui {
41
79
  "backgroundColor": ent:backgroundColor || "#87cefa",
42
80
  "x": ent:x || 100,
43
81
  "y": ent:y || 100,
44
- "width": ent:width || 100,
45
- "height": ent:height || 100
82
+ "width": ent:width || 125,
83
+ "height": ent:height || 90
46
84
  }
47
85
  }
86
+ /**
87
+ * This pico's channels (with their policies) and installed rulesets, plus the
88
+ * UI channels of its parent and children. A quick way to see what a pico is.
89
+ * @returns Map "{ eci, parent, children, channels, rulesets }"
90
+ */
48
91
  pico = function(){
49
92
  return {
50
93
  "eci": uiECI(),
@@ -54,6 +97,12 @@ ruleset io.picolabs.pico-engine-ui {
54
97
  "rulesets": ctx:rulesets
55
98
  }
56
99
  }
100
+ /**
101
+ * Recent activity on this pico, grouped by transaction, newest first: each
102
+ * incoming event or query with the rules it selected, klog output, and errors.
103
+ * The developer UI's own queries are left out.
104
+ * @returns Array "[ { txnId, time, header, entries } ]"
105
+ */
57
106
  logs = function(){
58
107
  logOther = function(entry){
59
108
  entry.delete("time")
@@ -141,7 +190,12 @@ ruleset io.picolabs.pico-engine-ui {
141
190
  { "domain": "engine_ui", "name": "del_channel" },
142
191
  { "domain": "engine_ui", "name": "update_channel" },
143
192
  { "domain": "engine_ui", "name": "testing_eci" },
193
+ { "domain": "engine_ui", "name": "testing_history_record" },
194
+ { "domain": "engine_ui", "name": "testing_history_clear" },
195
+ { "domain": "engine_ui", "name": "testing_saved_upsert" },
196
+ { "domain": "engine_ui", "name": "testing_saved_delete" },
144
197
  { "domain": "engine", "name": "started" },
198
+ { "domain": "engine", "name": "ruleset_set_changed" },
145
199
  { "domain": "wrangler", "name": "subscription" },
146
200
  { "domain": "wrangler", "name": "relationship" },
147
201
  { "domain": "wrangler", "name": "pending_subscription_approval" },
@@ -154,7 +208,12 @@ ruleset io.picolabs.pico-engine-ui {
154
208
  { "domain": "wrangler", "name": "relationship_cancellation" },
155
209
  { "domain": "wrangler", "name": "set_public_intro" },
156
210
  { "domain": "wrangler", "name": "send_event_on_subs" },
157
- { "domain": "wrangler", "name": "send_event_on_relationships" }
211
+ { "domain": "wrangler", "name": "send_event_on_relationships" },
212
+ { "domain": "wrangler", "name": "child_deleted" },
213
+ { "domain": "wrangler", "name": "new_child_request" },
214
+ { "domain": "wrangler", "name": "new_child_created" },
215
+ { "domain": "wrangler", "name": "install_ruleset_request" },
216
+ { "domain": "wrangler", "name": "new_channel_request" }
158
217
  ],
159
218
  "deny": []
160
219
  }
@@ -163,18 +222,23 @@ ruleset io.picolabs.pico-engine-ui {
163
222
  {
164
223
  "allow": [
165
224
  { "rid": "*", "name": "__testing" },
225
+ { "rid": "*", "name": "__consoleEval" },
166
226
  { "rid": "io.picolabs.pico-engine-ui", "name": "uiECI" },
167
227
  { "rid": "io.picolabs.pico-engine-ui", "name": "box" },
168
228
  { "rid": "io.picolabs.pico-engine-ui", "name": "pico" },
169
229
  { "rid": "io.picolabs.pico-engine-ui", "name": "logs" },
170
230
  { "rid": "io.picolabs.pico-engine-ui", "name": "testingECI" },
231
+ { "rid": "io.picolabs.pico-engine-ui", "name": "testingHistory" },
232
+ { "rid": "io.picolabs.pico-engine-ui", "name": "testingSaved" },
171
233
  { "rid": "io.picolabs.pico-engine-ui", "name": "name" },
172
234
  { "rid": "io.picolabs.subscription", "name": "established" },
173
235
  { "rid": "io.picolabs.subscription", "name": "inbound" },
174
236
  { "rid": "io.picolabs.subscription", "name": "outbound" },
175
237
  { "rid": "io.picolabs.subscription", "name": "wellKnown_Rx" },
176
238
  { "rid": "io.picolabs.wrangler", "name": "myDid" },
177
- { "rid": "io.picolabs.wrangler", "name": "publicIntro" }
239
+ { "rid": "io.picolabs.wrangler", "name": "publicIntro" },
240
+ { "rid": "io.picolabs.wrangler", "name": "rulesetSchema" },
241
+ { "rid": "io.picolabs.wrangler", "name": "picoSchema" }
178
242
  ],
179
243
  "deny": []
180
244
  }
@@ -183,6 +247,12 @@ ruleset io.picolabs.pico-engine-ui {
183
247
  "#FFB347", "#77DD77", "#B19CD9", "#FF6961", "#FDFD96",
184
248
  "#84B6F4", "#FFD1DC", "#C9A0DC", "#98FB98", "#E6E6FA"
185
249
  ]
250
+ // Grid slot from live children only — not ent:child_ui_ecis map size (stale
251
+ // entries survive pico deletion and were inflating layout Y on every recreate).
252
+ childLayoutIndex = function(familyEci) {
253
+ idx = ctx:children.index(familyEci)
254
+ idx.isnull() => ctx:children.length() - 1 | idx
255
+ }
186
256
  refreshUiChannel = defaction() {
187
257
  ctx:upsertChannel(
188
258
  tags = ["engine", "ui"],
@@ -191,6 +261,9 @@ ruleset io.picolabs.pico-engine-ui {
191
261
  )
192
262
  }
193
263
  }
264
+ // engine_ui events are the developer UI's private protocol and are deliberately
265
+ // not discoverable. Their public equivalents are wrangler events
266
+ // (new_child_request, install_ruleset_request, new_channel_request, …).
194
267
  rule setup {
195
268
  select when engine_ui setup
196
269
  refreshUiChannel()
@@ -218,11 +291,11 @@ ruleset io.picolabs.pico-engine-ui {
218
291
  pre {
219
292
  uiEci = event:attr("uiEci")
220
293
  familyEci = event:attr("eci")
221
- childIndex = ent:child_ui_ecis.defaultsTo({}).keys().length()
294
+ childIndex = childLayoutIndex(familyEci)
222
295
  gridCol = childIndex % 4
223
296
  gridRow = (childIndex - childIndex % 4) / 4
224
- layoutX = ent:x.defaultsTo(100) + 48 + gridCol * 118
225
- layoutY = ent:y.defaultsTo(100) + 48 + gridRow * 98
297
+ layoutX = ent:x.defaultsTo(100) + 48 + gridCol * 143
298
+ layoutY = ent:y.defaultsTo(100) + 48 + gridRow * 108
226
299
  layoutColor = childPalette[childIndex % childPalette.length]
227
300
  }
228
301
  if uiEci && familyEci then
@@ -233,8 +306,8 @@ ruleset io.picolabs.pico-engine-ui {
233
306
  attrs={
234
307
  "x": layoutX,
235
308
  "y": layoutY,
236
- "width": 100,
237
- "height": 100,
309
+ "width": 125,
310
+ "height": 90,
238
311
  "backgroundColor": layoutColor,
239
312
  "parentUiEci": uiECI()
240
313
  }
@@ -245,17 +318,14 @@ ruleset io.picolabs.pico-engine-ui {
245
318
  }
246
319
  rule spread_children_on_startup {
247
320
  select when engine started
248
- foreach ent:child_ui_ecis.defaultsTo({}).keys() setting(familyEci)
321
+ foreach ctx:children setting(familyEci)
249
322
  pre {
250
323
  uiEci = ent:child_ui_ecis{familyEci}
251
- childKeys = ent:child_ui_ecis.defaultsTo({}).keys()
252
- childIndex = childKeys.index(familyEci)
253
- originX = ent:x.defaultsTo(100)
254
- originY = ent:y.defaultsTo(100)
324
+ childIndex = childLayoutIndex(familyEci)
255
325
  gridCol = childIndex % 4
256
326
  gridRow = (childIndex - childIndex % 4) / 4
257
- layoutX = originX + 48 + gridCol * 118
258
- layoutY = originY + 48 + gridRow * 98
327
+ layoutX = ent:x.defaultsTo(100) + 48 + gridCol * 143
328
+ layoutY = ent:y.defaultsTo(100) + 48 + gridRow * 108
259
329
  layoutColor = childPalette[childIndex % childPalette.length]
260
330
  }
261
331
  if uiEci && ctx:query(uiEci, ctx:rid, "needsStartupLayout") then
@@ -266,8 +336,8 @@ ruleset io.picolabs.pico-engine-ui {
266
336
  attrs={
267
337
  "x": layoutX,
268
338
  "y": layoutY,
269
- "width": 100,
270
- "height": 100,
339
+ "width": 125,
340
+ "height": 90,
271
341
  "backgroundColor": layoutColor,
272
342
  "parentUiEci": uiECI()
273
343
  }
@@ -281,6 +351,21 @@ ruleset io.picolabs.pico-engine-ui {
281
351
  ent:child_ui_ecis{[familyEci]} := ctx:query(familyEci, ctx:rid, "uiECI")
282
352
  }
283
353
  }
354
+ rule prune_stale_child_ui_ecis {
355
+ select when engine started
356
+ foreach ent:child_ui_ecis.defaultsTo({}).keys() setting(familyEci)
357
+ always {
358
+ clear ent:child_ui_ecis{familyEci}
359
+ if ctx:children.index(familyEci).isnull()
360
+ }
361
+ }
362
+ rule forget_child_ui_eci {
363
+ select when wrangler child_deleted
364
+ eci re#(.+)# setting(familyEci)
365
+ always {
366
+ clear ent:child_ui_ecis{familyEci}
367
+ }
368
+ }
284
369
  rule backfill_parent_ui_eci {
285
370
  select when engine started
286
371
  if ctx:parent && ent:parent_ui_eci.isnull() then noop()
@@ -312,6 +397,9 @@ ruleset io.picolabs.pico-engine-ui {
312
397
  .head()
313
398
  }
314
399
  ctx:delPico(delEci)
400
+ always {
401
+ clear ent:child_ui_ecis{delEci} if delEci
402
+ }
315
403
  }
316
404
  rule install {
317
405
  select when engine_ui install
@@ -333,16 +421,51 @@ ruleset io.picolabs.pico-engine-ui {
333
421
  }
334
422
  rule flush {
335
423
  select when engine_ui flush
336
- ctx:flush(url=event:attrs{"url"})
424
+ pre {
425
+ url = event:attrs{"url"}
426
+ validation = ctx:validate(url)
427
+ ok = validation{"ok"}
428
+ validate_errors = validation{"errors"}
429
+ validate_warnings = validation{"warnings"}
430
+ validate_rid = validation{"rid"}
431
+ }
432
+ if ok then every {
433
+ ctx:flush(url=url)
434
+ }
435
+ fired {
436
+ raise engine_ui event "flush_succeeded" attributes {"url": url}
437
+ }
438
+ else {
439
+ raise wrangler event "ruleset_flush_failed" attributes
440
+ {"url": url, "rid": validate_rid, "errors": validate_errors, "warnings": validate_warnings}
441
+ }
337
442
  }
338
443
  rule refresh_ui_channel_after_flush {
339
- select when engine_ui flush
444
+ select when engine_ui flush_succeeded
340
445
  pre {
341
446
  url = event:attrs{"url"} || ""
342
447
  self_flush = url.match(re#io\.picolabs\.pico-engine-ui#)
343
448
  }
344
449
  if self_flush then refreshUiChannel()
345
450
  }
451
+ // Reinstall the flushed ruleset on this pico so the new KRL takes effect.
452
+ // The rid comes from the installed ruleset whose url matches: the UI sends the
453
+ // url from pico(){"rulesets"}, so it is exactly the installed ruleset's url.
454
+ // (Previously the rid was parsed out of the url, which never matched —
455
+ // substr(0, 11) is "io.picolabs" without the dot — and truncated dotted rids.)
456
+ rule reinstall_after_flush {
457
+ select when engine_ui flush_succeeded
458
+ pre {
459
+ url = event:attrs{"url"} || ""
460
+ rid = ctx:rulesets
461
+ .filter(function(rs){ rs{"url"} == url })
462
+ .head(){"rid"}
463
+ }
464
+ if url && rid then noop()
465
+ fired {
466
+ raise wrangler event "install_ruleset_request" attributes {"rid": rid, "url": url}
467
+ }
468
+ }
346
469
  rule new_channel {
347
470
  select when engine_ui new_channel
348
471
  ctx:newChannel(
@@ -371,4 +494,69 @@ ruleset io.picolabs.pico-engine-ui {
371
494
  ent:testingECI := event:attrs{"eci"}
372
495
  }
373
496
  }
497
+
498
+ rule testing_history_record {
499
+ select when engine_ui testing_history_record
500
+ pre {
501
+ rid = event:attrs{"rid"}
502
+ entry = event:attrs{"entry"}
503
+ prior = ent:testing_history{rid}.defaultsTo([])
504
+ merged = [entry].append(prior)
505
+ }
506
+ if rid && entry then noop()
507
+ fired {
508
+ ent:testing_history := ent:testing_history.defaultsTo({})
509
+ ent:testing_history{rid} := merged.length() > testingHistoryCap
510
+ => merged.slice(0, testingHistoryCap) |
511
+ merged
512
+ }
513
+ }
514
+
515
+ rule testing_history_clear {
516
+ select when engine_ui testing_history_clear
517
+ pre {
518
+ rid = event:attrs{"rid"}
519
+ clearAll = rid.isnull() || rid == ""
520
+ }
521
+ if clearAll then noop()
522
+ fired {
523
+ ent:testing_history := {}
524
+ }
525
+ else {
526
+ ent:testing_history := ent:testing_history.defaultsTo({})
527
+ ent:testing_history{rid} := []
528
+ }
529
+ }
530
+
531
+ rule testing_saved_upsert {
532
+ select when engine_ui testing_saved_upsert
533
+ pre {
534
+ rid = event:attrs{"rid"}
535
+ entry = event:attrs{"entry"}
536
+ entryId = entry.get("id")
537
+ prior = ent:testing_saved{rid}.defaultsTo([])
538
+ rest = prior.filter(function(e){e.get("id") != entryId})
539
+ merged = [entry].append(rest)
540
+ }
541
+ if rid && entry && entryId then noop()
542
+ fired {
543
+ ent:testing_saved := ent:testing_saved.defaultsTo({})
544
+ ent:testing_saved{rid} := merged
545
+ }
546
+ }
547
+
548
+ rule testing_saved_delete {
549
+ select when engine_ui testing_saved_delete
550
+ pre {
551
+ rid = event:attrs{"rid"}
552
+ id = event:attrs{"id"}
553
+ prior = ent:testing_saved{rid}.defaultsTo([])
554
+ merged = prior.filter(function(e){e.get("id") != id})
555
+ }
556
+ if rid && id then noop()
557
+ fired {
558
+ ent:testing_saved := ent:testing_saved.defaultsTo({})
559
+ ent:testing_saved{rid} := merged
560
+ }
561
+ }
374
562
  }
@@ -0,0 +1,97 @@
1
+ ruleset io.picolabs.portable_subtree {
2
+ meta {
3
+ name "Portable subtree"
4
+ description <<
5
+ Optional wrangler utility for copying a pico subtree (rulesets, entity state,
6
+ channels, schedules, and Layer 2 identity) to another parent — on the same
7
+ engine or a different one. Not installed by default.
8
+
9
+ Export (install on an ancestor of the subtree to copy):
10
+ portable_subtree:exportSubtree(subtreeRootPicoId, secret)
11
+ → encrypted blob (transfer manually to the destination engine)
12
+
13
+ Inspect a blob before import (same secret):
14
+ portable_subtree:summarizeExportBlob(blob, secret)
15
+
16
+ Import (install on the adopting parent):
17
+ raise portable_subtree event "import"
18
+ attributes { "blob": "...", "secret": "..." }
19
+ → portable_subtree:imported event; read result with portable_subtree:lastImport()
20
+
21
+ The importer must ensure the recipient mesh provides any platform services
22
+ the subtree relied on from ancestors in the donor mesh (e.g. import a
23
+ Manifold app pico under a Manifold parent, not a bare wrangler root).
24
+
25
+ After import, delete the source subtree manually if you no longer need it.
26
+ >>
27
+ author "PICOLABS"
28
+
29
+ provides exportSubtree, lastImport, summarizeExportBlob
30
+ shares exportSubtree, lastImport, summarizeExportBlob
31
+ }
32
+
33
+ global {
34
+ /**
35
+ * Export a descendant subtree (or this pico itself) as an encrypted blob:
36
+ * rulesets, entity state, channels, schedules, and Layer 2 identity. Read-only;
37
+ * the source subtree is untouched. Transfer the blob to the adopting parent and
38
+ * send it portable_subtree:import there with the same secret.
39
+ * @param subtreeRootPicoId String "pico id of the subtree root; this pico's own id exports this pico"
40
+ * @param secret String "encryption secret; the importer needs the same one"
41
+ * @returns String "encrypted export blob"
42
+ */
43
+ exportSubtree = function(subtreeRootPicoId, secret) {
44
+ dido:exportPortableSubtree(subtreeRootPicoId, secret)
45
+ }
46
+
47
+ /**
48
+ * Result of the most recent portable_subtree:import on this pico (the same
49
+ * attrs as the portable_subtree:imported event), or null if none.
50
+ * @returns Map
51
+ */
52
+ lastImport = function() {
53
+ ent:lastImport
54
+ }
55
+
56
+ /**
57
+ * Inspect an export blob before importing it: subtree root name, relationship
58
+ * count, rulesets with entity state, and similar. Read-only.
59
+ * @param blob String "export blob from exportSubtree"
60
+ * @param secret String "the secret used to export it"
61
+ * @returns Map "{ wranglerName, establishedCount, entRulesets, … }"
62
+ */
63
+ summarizeExportBlob = function(blob, secret) {
64
+ dido:summarizePortableSubtreeExport(blob, secret)
65
+ }
66
+ }
67
+
68
+ /**
69
+ * Import an exported subtree as a child of this pico. Rulesets, entity state,
70
+ * channels, schedules, and identity are restored, and Layer 2 relationships are
71
+ * relocated so they survive the move. The result is stored for lastImport() and
72
+ * raised as portable_subtree:imported. This pico must provide any platform
73
+ * services the subtree relied on in its old mesh (e.g. import a Manifold app
74
+ * pico under a Manifold parent). The source subtree is not deleted.
75
+ * @attr blob String "export blob from exportSubtree"
76
+ * @attr secret String "the secret used to export it"
77
+ * @attr renewIngress Boolean optional "mint a fresh DIDComm ingress channel when relocating each pico's did:webvh (default true)"
78
+ * @attr bootstrapDisplayName String optional "display name for the imported root"
79
+ * @example "import" { "blob": "<blob from exportSubtree>", "secret": "<secret>" }
80
+ */
81
+ rule import_subtree {
82
+ select when portable_subtree import
83
+ pre {
84
+ blob = event:attr("blob")
85
+ secret = event:attr("secret")
86
+ result = dido:importPortableSubtree(blob, secret, {
87
+ "renewIngress": event:attr("renewIngress").defaultsTo(true),
88
+ "parentChannelEci": event:eci,
89
+ "bootstrapDisplayName": event:attr("bootstrapDisplayName")
90
+ })
91
+ }
92
+ fired {
93
+ ent:lastImport := result
94
+ raise portable_subtree event "imported" attributes result
95
+ }
96
+ }
97
+ }