pico-engine 1.9.5 → 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 (126) hide show
  1. package/README.md +11 -5
  2. package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
  3. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
  4. package/demos/echo/com.example.echo.bootstrap.krl +10 -7
  5. package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
  6. package/demos/json_query/README.md +11 -0
  7. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  8. package/demos/json_query/com.example.json_query.krl +162 -0
  9. package/demos/json_query/try-it.md +5 -0
  10. package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
  11. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
  12. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
  13. package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
  14. package/demos/try-it-order.json +1 -1
  15. package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
  16. package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
  17. package/dist/cli.js +5 -1
  18. package/dist/engineConfig.js +1 -1
  19. package/dist/identity/portableMove.js +5 -1
  20. package/dist/index.js +44 -12
  21. package/dist/internalAccess.js +110 -0
  22. package/dist/oauth/OAuthService.js +172 -10
  23. package/dist/oauth/acg.js +194 -24
  24. package/dist/oauth/cimd.js +381 -0
  25. package/dist/oauth/discovery.js +175 -0
  26. package/dist/runMcp.js +1 -1
  27. package/dist/server.js +197 -48
  28. package/dist/subtreeWrangler.js +8 -5
  29. package/dist/uiChannelPolicies.js +2 -0
  30. package/krl/io.picolabs.pds.krl +109 -21
  31. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  32. package/krl/io.picolabs.wrangler.krl +21 -9
  33. package/mcp/devResources.js +52 -0
  34. package/mcp/devTools.js +40 -9
  35. package/mcp/docs/CLAUDE.md +3 -2
  36. package/mcp/docs/cookbook/README.md +23 -0
  37. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  38. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  39. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  40. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  41. package/mcp/docs/cookbook/collection/README.md +21 -0
  42. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  43. package/mcp/docs/cookbook/echo/README.md +19 -0
  44. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  45. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  46. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  47. package/mcp/docs/cookbook/json_query/README.md +26 -0
  48. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  49. package/mcp/docs/cookbook/kblog/README.md +60 -0
  50. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  51. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  52. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  53. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  54. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  55. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  56. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  57. package/mcp/docs/cookbook/secrets/README.md +25 -0
  58. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  59. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  60. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  61. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  62. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  63. package/mcp/docs/developing/README.md +28 -0
  64. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  65. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  66. package/mcp/docs/developing/converting-time-formats.md +28 -0
  67. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  68. package/mcp/docs/developing/decoding-form-data.md +67 -0
  69. package/mcp/docs/developing/engine-log-files.md +34 -0
  70. package/mcp/docs/developing/event-loop.md +77 -0
  71. package/mcp/docs/developing/events-from-email.md +80 -0
  72. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  73. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  74. package/mcp/docs/developing/misconceptions.md +467 -0
  75. package/mcp/docs/developing/names-and-scope.md +44 -0
  76. package/mcp/docs/developing/postman.md +159 -0
  77. package/mcp/docs/developing/querying-another-pico.md +47 -0
  78. package/mcp/docs/developing/singleton-picos.md +36 -0
  79. package/mcp/docs/developing/tabular-data.md +67 -0
  80. package/mcp/docs/developing/tips.md +251 -0
  81. package/mcp/docs/developing/webhook-signatures.md +56 -0
  82. package/mcp/docs/developing/workflow.md +106 -0
  83. package/mcp/docs/exp/README.md +46 -0
  84. package/mcp/docs/exp/event.md +110 -0
  85. package/mcp/docs/exp/query.md +94 -0
  86. package/mcp/docs/lessons/README.md +59 -0
  87. package/mcp/docs/lessons/events-and-queries.md +247 -0
  88. package/mcp/docs/lessons/gossip.md +28 -0
  89. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  90. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  91. package/mcp/docs/lessons/pico-state.md +267 -0
  92. package/mcp/docs/lessons/pico-views.md +290 -0
  93. package/mcp/docs/lessons/quickstart.md +157 -0
  94. package/mcp/docs/lessons/relationships.md +530 -0
  95. package/mcp/docs/lessons/scatter-gather.md +362 -0
  96. package/mcp/docs/pico-engine.md +7 -5
  97. package/mcp/docs/pico-overview.md +3 -3
  98. package/mcp/docs/wrangler/README.md +47 -0
  99. package/mcp/docs/wrangler/channels.md +235 -0
  100. package/mcp/docs/wrangler/oauth.md +56 -0
  101. package/mcp/docs/wrangler/pds.md +423 -0
  102. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  103. package/mcp/docs/wrangler/relationships.md +297 -0
  104. package/mcp/docs/wrangler/wrangler.md +253 -0
  105. package/mcp/docs/wrangler/xmlui.md +60 -0
  106. package/mcp/engineClient.js +57 -5
  107. package/mcp/mcpScopes.js +118 -0
  108. package/mcp/meshHttp.js +151 -45
  109. package/mcp/runStdio.js +2 -0
  110. package/mcp/subtreeTools.js +184 -0
  111. package/mcp/tryItTools.js +202 -0
  112. package/package.json +14 -8
  113. package/public/pico-engine-ui.js +26 -26
  114. package/src/cli.ts +6 -2
  115. package/src/engineConfig.ts +5 -2
  116. package/src/identity/portableMove.ts +6 -1
  117. package/src/index.ts +469 -430
  118. package/src/internalAccess.ts +127 -0
  119. package/src/oauth/OAuthService.ts +243 -11
  120. package/src/oauth/acg.ts +289 -25
  121. package/src/oauth/cimd.ts +508 -0
  122. package/src/oauth/discovery.ts +233 -0
  123. package/src/runMcp.ts +3 -1
  124. package/src/server.ts +252 -52
  125. package/src/subtreeWrangler.ts +17 -5
  126. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,423 @@
1
+ # Pico data store
2
+
3
+ *Ruleset: `io.picolabs.pds`, installed on every pico. For every event and function, see the [API reference](/rulesets/io.picolabs.pds).*
4
+
5
+ [Relationships](/wrangler/relationships) answer "how do two picos talk to each other?" The pico data store (PDS) answers "where does a pico keep its data, and how do rulesets read and write it consistently?"
6
+
7
+ Without PDS, each application ruleset makes its own entity variables (`ent:contactInfo`, `ent:thingInfo`, …). Display names end up in Wrangler, contact cards in one ruleset, configuration in another. PDS is one shared data service on every pico, with three layers:
8
+
9
+ | Layer | Entity variable | Purpose |
10
+ |-------|-----------------|---------|
11
+ | Profile | `ent:profile` | This pico's display identity: name, description, photo. A person's profile only if this pico stands for a person |
12
+ | General | `ent:general` | Namespaced key-value data for apps and domains |
13
+ | Settings | `ent:settings` | Per-ruleset configuration, keyed by rid |
14
+
15
+ Design principles:
16
+
17
+ - **PDS owns the data.** Apps don't write `ent:profile`, `ent:general`, or `ent:settings` themselves. They raise `pds` events; PDS rules store the data and announce the change.
18
+ - **Reads go through shared functions.** Other rulesets `use module io.picolabs.pds` and call its functions (`profile`, `items`, `config_value`, …).
19
+ - **Writes are events.** Raise `pds:updated_profile`, `pds:new_data_available`, and so on; select `pds:profile_updated`, `pds:data_added`, and so on to react.
20
+ - **One PDS per pico.** The engine installs it on the root pico, and Wrangler installs it on every child.
21
+
22
+ PDS doesn't replace relationships, channels, or Wrangler; it complements them. Relationships are the wire; PDS is the notebook each pico keeps about itself. Not everything belongs in it: see the next section.
23
+
24
+ ## What belongs in PDS (and what doesn't)
25
+
26
+ PDS is a pico's shared data plane, but application rulesets still have their own entity variables. Use PDS when the data is shared, queried, or part of the pico's display identity. Keep data in the app's ruleset when it is private, derived, short-lived, or changes very often.
27
+
28
+ ### Profile, on every pico
29
+
30
+ Put in the profile (`pds:updated_profile`, read with `pds:profile()`):
31
+
32
+ | Data | Examples |
33
+ |------|----------|
34
+ | Display name | Labels for things, communities, owners, and registries in UI lists and notifications |
35
+ | Short description | A community's blurb, a thing's subtitle |
36
+ | Photo or avatar | An owner's photo, a thing's icon |
37
+ | Contact details (on an owner's pico) | Email and phone, for notifications |
38
+
39
+ The profile is the stable surface other picos read: frameworks, notifications, and peers use `wrangler:picoQuery(eci, "io.picolabs.pds", "profile", …)` without knowing each app's layout. When PDS is installed, it copies the Wrangler name into the profile if the profile has none.
40
+
41
+ In application rulesets, prefer `pds:profile("name")` to `wrangler:name()` for anything shown to people.
42
+
43
+ ### General data
44
+
45
+ Put in general (`pds:new_data_available`, by namespace and key):
46
+
47
+ | Situation | Example |
48
+ |-----------|---------|
49
+ | Two or more rulesets on the same pico need the data | A contact card read by a lost-and-found app and by a public query channel |
50
+ | Other picos read it with `picoQuery(..., "io.picolabs.pds", "items", …)` | A registry's ECI stored on a thing, for tag lookup |
51
+ | A namespace documented for others to rely on | `general.safeandmine.contact`, `general.sensor.last_reading` |
52
+
53
+ Keep in the app's own entity variables (and raise the app's own events):
54
+
55
+ | Situation | Example |
56
+ |-----------|---------|
57
+ | One ruleset writes it and nothing else reads it | An internal list of channels, pending UI state |
58
+ | A cache rebuilt from relationships and PDS reads | `ent:thingInfo` on a thing pico |
59
+ | An index rebuilt from Wrangler events | A hub's list of the things and communities it holds (the canonical name is in each child's profile) |
60
+ | Short-lived UI state | Layout, colors, badge counts, notification inbox rows |
61
+ | High-volume telemetry | Raw sensor readings. Use PDS general only if other rulesets must query the latest value |
62
+
63
+ ### Settings
64
+
65
+ Put in settings (`pds:add_settings`, keyed by ruleset rid):
66
+
67
+ - Per-app configuration and feature flags (`shareEmail`, thresholds, notification switches).
68
+ - Data the owning ruleset reads with `pds:config_value("key")`, which uses the calling ruleset's rid.
69
+
70
+ Keep operational state (the last run's id, timers, in-flight maps) in the app's ruleset, unless another ruleset must read it.
71
+
72
+ ### A checklist
73
+
74
+ - Needs a stable API that other rulesets or picos read? PDS: profile, general, or settings, by shape.
75
+ - The pico's display identity in UIs or notifications? The profile.
76
+ - Only this ruleset touches it? The app's own entity variables.
77
+ - Rebuilt from relationship, Wrangler, or framework events? A derived cache in the app's ruleset, not duplicated in PDS.
78
+ - Layout, cache, or scratch state? The app's own entity variables.
79
+
80
+ ### Mirroring (planned)
81
+
82
+ Mirrors of a pico (copies kept elsewhere) are planned around a selective event log: replaying Wrangler, framework, and `pds` events, plus events apps opt in, rebuilds a pico's state. `pds` writes are good events for that log. A PDS snapshot (profile, general, settings, and installed rulesets) is a simpler export. App entity variables are views rebuilt on replay. Don't move data into PDS only for mirroring; move it when it is shared.
83
+
84
+ ## Using PDS in KRL
85
+
86
+ In a ruleset that reads PDS data on the same pico:
87
+
88
+ ```krl
89
+ meta {
90
+ use module io.picolabs.pds alias pds
91
+ }
92
+ ```
93
+
94
+ To read PDS on another pico, query it with `wrangler:picoQuery` on a channel whose query policy allows `io.picolabs.pds`:
95
+
96
+ ```krl
97
+ displayName = wrangler:picoQuery(thing_eci, "io.picolabs.pds", "profile", {"key": "name"}){"profile"}
98
+ ```
99
+
100
+ When PDS is installed, it creates a channel tagged `pds` that allows `pds` events and `io.picolabs.pds` queries, for HTTP access. On the root pico, it also makes sure the channel exists each time the engine starts. The developer UI's channel doesn't allow PDS queries.
101
+
102
+ ## Reading data
103
+
104
+ The functions return a map with `status` (`"success"` or `"failed"`) and the data under `profile`, `general`, or `settings`.
105
+
106
+ ### Profile
107
+
108
+ `profile(key)` reads this pico's profile: how the pico presents itself. Each pico has its own. A thing's name isn't its owner's name unless an app copies it there.
109
+
110
+ | Call | Returns |
111
+ |------|---------|
112
+ | `profile()` | The whole profile |
113
+ | `profile("name")` | One field, under `profile` |
114
+
115
+ ```krl
116
+ allProfile = pds:profile(){"profile"}
117
+ name = pds:profile("name"){"profile"}
118
+ ```
119
+
120
+ An empty profile looks like this; the default `photo` is a placeholder image, as a `data:` URI:
121
+
122
+ ```json
123
+ {"name": "", "description": "", "photo": "data:image/svg+xml;base64,..."}
124
+ ```
125
+
126
+ ### General items
127
+
128
+ `items(namespace, key)`:
129
+
130
+ | Call | Returns |
131
+ |------|---------|
132
+ | `items(null, null)` | All of `ent:general` (use sparingly) |
133
+ | `items("myapp", null)` | Every key in the `myapp` namespace |
134
+ | `items("myapp", "contact")` | One value |
135
+
136
+ ```krl
137
+ card = pds:items("safeandmine", "contact"){"general"}
138
+ allTags = pds:items("safeandmine", null){"general"}
139
+ ```
140
+
141
+ ### Settings
142
+
143
+ | Function | Purpose |
144
+ |----------|---------|
145
+ | `settings(rid, key, detail)` | A ruleset's settings entry, or part of it |
146
+ | `setting_data(rid)` | The `Data` map for a ruleset |
147
+ | `setting_data_value(rid, setKey)` | One key in it |
148
+ | `config_value(setKey)` | One key of the calling ruleset's own data |
149
+
150
+ `config_value` lets a ruleset read its own preferences without naming its rid:
151
+
152
+ ```krl
153
+ threshold = pds:config_value("threshold")
154
+ ```
155
+
156
+ ## Writing data
157
+
158
+ ### The profile
159
+
160
+ Raise `pds:updated_profile` with any of the profile's fields. It merges into the profile; fields you leave out keep their values. PDS sets `_created` on the first write and `_modified` on every one.
161
+
162
+ ```krl
163
+ raise pds event "updated_profile" attributes {
164
+ "name": "Blue Backpack",
165
+ "description": "Phil's day pack",
166
+ "photo": "https://example.com/photo.jpg"
167
+ }
168
+ ```
169
+
170
+ PDS raises `pds:profile_updated` with a `_status` of `"success"` or `"failure"`.
171
+
172
+ ```krl
173
+ rule on_profile_updated {
174
+ select when pds profile_updated
175
+ pre {
176
+ name = event:attr("name")
177
+ status = event:attr("_status")
178
+ }
179
+ if status == "success" then send_directive("profile saved", {"name": name})
180
+ }
181
+ ```
182
+
183
+ On a thing or a community, you're setting that pico's identity, not its owner's. To change a person's contact details, write to the owner's pico.
184
+
185
+ ### General data
186
+
187
+ Data is organized by namespace and key. Values can be anything, including maps. Use namespaces so apps don't collide (`safeandmine`, `sensor`, …).
188
+
189
+ Add or replace an item with `pds:new_data_available`. PDS raises `pds:data_added`:
190
+
191
+ ```krl
192
+ raise pds event "new_data_available" attributes {
193
+ "namespace": "safeandmine",
194
+ "key": "contact",
195
+ "value": {"email": "owner@example.com", "phone": "555-0100", "shareEmail": false}
196
+ }
197
+ ```
198
+
199
+ Merge into a map item with `pds:updated_data_available`, whose `value` is the keys to change. PDS raises `pds:data_updated`:
200
+
201
+ ```krl
202
+ raise pds event "updated_data_available" attributes {
203
+ "namespace": "safeandmine",
204
+ "key": "contact",
205
+ "value": {"phone": "555-0199"}
206
+ }
207
+ ```
208
+
209
+ Replace a whole namespace with `pds:map_item`, whose `mapvalues` is JSON-encoded. PDS raises `pds:new_map_added`:
210
+
211
+ ```krl
212
+ raise pds event "map_item" attributes {
213
+ "namespace": "safeandmine",
214
+ "mapvalues": {"tag1": "eci-abc", "tag2": "eci-def"}.encode()
215
+ }
216
+ ```
217
+
218
+ Remove one item with `pds:remove_old_data` (`namespace`, `key`), which raises `pds:data_deleted`, or a whole namespace with `pds:remove_namespace` (`namespace`), which raises `pds:namespace_deleted`.
219
+
220
+ ### Settings
221
+
222
+ Settings are keyed by rid. Each entry has a `name`, the `rid`, a `data` map, an optional `schema`, and an optional `secret` list of data-key names. `pds:add_settings` sets one value, and PDS raises `pds:settings_added`.
223
+
224
+ A secret key is marked with `"secret": true` on that write, `"secret": ["apiKey"]`, or a schema entry `{ "key": "apiKey", "secret": true }`. `settings` and `get_setting_data_value` then return `{ "secret": true, "set": true }` (or `set: false` when the key has no value). They never return the value. The ruleset that owns the setting reads it with `config_value`, which uses `meta:callingRID()`. The value is omitted from engine logs. `getChannelEci` is available to rulesets on the pico and is not a shared query. The `pds` channel does not accept `clear_all_data`.
225
+
226
+ ```krl
227
+ raise pds event "add_settings" attributes {
228
+ "name": "SafeAndMine",
229
+ "keyed_rid": "io.picolabs.safeandmine",
230
+ "schema": [],
231
+ "data_key": "shareEmail",
232
+ "value": true
233
+ }
234
+ ```
235
+
236
+ ### Reacting to changes
237
+
238
+ | Event | Raised when |
239
+ |-------|-------------|
240
+ | `pds:data_added` | An item was added |
241
+ | `pds:data_updated` | An item was merged into |
242
+ | `pds:data_deleted` | An item was removed |
243
+ | `pds:namespace_deleted` | A namespace was removed |
244
+ | `pds:new_map_added` | A namespace was replaced |
245
+ | `pds:profile_updated` | The profile changed |
246
+ | `pds:settings_added` | A settings entry changed |
247
+
248
+ ```krl
249
+ rule contact_changed {
250
+ select when pds data_updated
251
+ where event:attr("namespace") == "safeandmine" && event:attr("keyvalue") == "contact"
252
+ always {
253
+ raise safeandmine event "contact_changed" attributes event:attrs
254
+ }
255
+ }
256
+ ```
257
+
258
+ ### Clearing everything
259
+
260
+ `pds:clear_all_data` erases the profile, all general data, and all settings, with no confirmation. It is for tests and developer tools. When an app is uninstalled, remove only its namespace and its settings; the profile should usually stay.
261
+
262
+ ## An example: an app on a thing pico
263
+
264
+ A lost-and-found app keeps its contact card in general data, uses the profile for the thing's name, and reads share flags from settings. Both `io.picolabs.pds` and the app are installed on the thing pico.
265
+
266
+ Save the card, through PDS:
267
+
268
+ ```krl
269
+ rule information_update {
270
+ select when safeandmine update
271
+ pre {
272
+ card = {
273
+ "email": event:attr("email").defaultsTo("").substr(0, 100),
274
+ "phone": event:attr("phone").defaultsTo("").substr(0, 100),
275
+ "message": event:attr("message").defaultsTo("").substr(0, 250),
276
+ "shareName": event:attr("shareName").as("Boolean").defaultsTo(false),
277
+ "shareEmail": event:attr("shareEmail").as("Boolean").defaultsTo(false)
278
+ }
279
+ }
280
+ always {
281
+ raise pds event "new_data_available" attributes {"namespace": "safeandmine", "key": "contact", "value": card}
282
+ }
283
+ }
284
+ ```
285
+
286
+ Read the public view of it, combining the profile and the card:
287
+
288
+ ```krl
289
+ rule get_information {
290
+ select when safeandmine information_requested
291
+ pre {
292
+ card = pds:items("safeandmine", "contact"){"general"}.defaultsTo({})
293
+ profileName = pds:profile("name"){"profile"}
294
+ result = card.put("name", card{"shareName"} => profileName | null)
295
+ }
296
+ send_directive("contact info", result)
297
+ }
298
+ ```
299
+
300
+ A notification uses the profile's name, not a copy in the app:
301
+
302
+ ```krl
303
+ rule notify {
304
+ select when safeandmine tag_scanned
305
+ pre {
306
+ thingName = pds:profile("name"){"profile"}
307
+ tagID = event:attr("tagID")
308
+ }
309
+ if tagID && thingName then
310
+ event:send({
311
+ "eci": owner_eci,
312
+ "domain": "notification",
313
+ "type": "added",
314
+ "attrs": {"thing": thingName, "message": "Your tag " + tagID + " has been scanned"}
315
+ })
316
+ }
317
+ ```
318
+
319
+ ## The data model
320
+
321
+ Only PDS rules write these three entity variables.
322
+
323
+ `ent:profile` is one map per pico. A thing's:
324
+
325
+ ```json
326
+ {
327
+ "name": "Blue Backpack",
328
+ "description": "Phil's hiking pack",
329
+ "photo": "https://…",
330
+ "_created": "20260609T120000+0000",
331
+ "_modified": "20260609T153000+0000"
332
+ }
333
+ ```
334
+
335
+ An owner's might also have `email` and `phone`. Any pico can have those fields.
336
+
337
+ `ent:general` is a tree of namespaces and keys:
338
+
339
+ ```
340
+ "safeandmine"
341
+ "contact" → { email, phone, message, shareName, … }
342
+ "registry_eci" → "<channel eci>"
343
+ "sensor"
344
+ "last_reading" → { … }
345
+ ```
346
+
347
+ In KRL, a path into it is `ent:general{[namespace, key]}`.
348
+
349
+ `ent:settings` is keyed by rid:
350
+
351
+ ```json
352
+ {
353
+ "io.picolabs.safeandmine": {
354
+ "name": "SafeAndMine",
355
+ "rid": "io.picolabs.safeandmine",
356
+ "data": {"shareEmail": false, "threshold": 60},
357
+ "schema": []
358
+ }
359
+ }
360
+ ```
361
+
362
+ Use predictable namespaces so apps coexist on one pico: the framework's (`manifold`), an app's (`safeandmine`), a domain's (`sensor`), or a ruleset's rid.
363
+
364
+ Don't store secrets in PDS general data unless the channels that can query it are restricted. Channel ECIs are capabilities; treat them as sensitive.
365
+
366
+ ## The protocol
367
+
368
+ Writing:
369
+
370
+ 1. An app's ruleset raises a `pds` event (`updated_profile`, `new_data_available`, …).
371
+ 2. A PDS rule checks the attributes and updates its entity variable.
372
+ 3. PDS raises a notification event (`profile_updated`, `data_added`, …) on the same pico.
373
+ 4. Other rulesets select the notification to react.
374
+
375
+ Apps never assign `ent:profile`, `ent:general`, or `ent:settings` themselves, which keeps storage in one place.
376
+
377
+ Reading: on the same pico, use the ruleset as a module; from another pico, `wrangler:picoQuery(eci, "io.picolabs.pds", function, params)` on a channel that allows it.
378
+
379
+ | | Relationships | PDS |
380
+ |-|---------------|-----|
381
+ | Problem | Communication between picos | Data storage within a pico |
382
+ | Mechanism | Channels and the relationship ruleset | Events and shared queries |
383
+ | Identity | `Tx`, `Rx`, roles | Profile name, namespaces |
384
+ | Installed | On every pico | On every pico |
385
+
386
+ ```
387
+ App ruleset PDS Other rulesets on the pico
388
+ |-- pds:updated_profile -->| |
389
+ | |-- merge ent:profile |
390
+ | |-- pds:profile_updated ------------>| (if they select it)
391
+ ```
392
+
393
+ ## Security
394
+
395
+ PDS is a data contract, not an authorization layer.
396
+
397
+ Entity variables belong to their ruleset, so another ruleset's `ent:contactInfo` is a different variable and can't overwrite PDS storage. Other rulesets reach PDS data by reading through the module or `picoQuery`, and by writing with `pds` events, which only PDS rules handle.
398
+
399
+ | Layer | Mechanism | What it protects |
400
+ |-------|-----------|------------------|
401
+ | Access from other picos | ECI and channel policy | Remote events and queries, including PDS queries |
402
+ | What runs on the pico | Who installs rulesets | Which rulesets run |
403
+ | Writes from the same pico | None today | — |
404
+
405
+ Any ruleset installed on a pico can raise `pds:updated_profile`, `pds:new_data_available`, `pds:clear_all_data`, and the rest. PDS doesn't check which ruleset raised them (it uses `meta:callingRID()` for settings reads, not for writes). So security depends on trusting every ruleset installed on the pico. Other picos need a channel that allows `pds` events or `io.picolabs.pds` queries; that's uncommon for writes.
406
+
407
+ Practical guidance:
408
+
409
+ - Install only rulesets you trust on production picos.
410
+ - Use namespaces consistently, so apps don't duplicate canonical data.
411
+ - Restrict query channels when general data includes sensitive fields.
412
+ - Treat `pds:clear_all_data` as destructive.
413
+
414
+ ### Planned
415
+
416
+ - Write authorization: checking `meta:callingRID()` on writes, so only the owning app writes its namespace.
417
+ - Engine-level workload identity and policy before events reach rulesets.
418
+ - Channel templates and install allowlists that limit what application rulesets can declare.
419
+
420
+ ## See also
421
+
422
+ - [Relationships](/wrangler/relationships): channels between picos, and roles
423
+ - [Managing channels](/wrangler/channels): ECIs and channel policies
@@ -0,0 +1,44 @@
1
+ # Portable subtrees: io.picolabs.portable_subtree
2
+
3
+ *Optional. Not installed by default. API reference: [io.picolabs.portable_subtree](/rulesets/io.picolabs.portable_subtree).*
4
+
5
+ `io.picolabs.portable_subtree` copies a pico and all its descendants to another parent, on the same engine or on another one. It copies their rulesets, entity state, channels, schedules, and identity. Each pico keeps its `did:webvh`, and its DID-based relationships are moved so they keep working.
6
+
7
+ ## Export
8
+
9
+ Install it on an ancestor of the pico you want to copy (the root pico works). Then query it:
10
+
11
+ ```krl
12
+ blob = portable_subtree:exportSubtree(subtree_root_pico_id, secret)
13
+ ```
14
+
15
+ The result is an encrypted blob. Move it to the destination however you like. Keep the secret separately: it isn't in the blob.
16
+
17
+ ## Inspect
18
+
19
+ Before importing, check what a blob holds, with the same secret:
20
+
21
+ ```krl
22
+ portable_subtree:summarizeExportBlob(blob, secret)
23
+ ```
24
+
25
+ ## Import
26
+
27
+ Install the ruleset on the pico that will be the new parent, and send it:
28
+
29
+ ```krl
30
+ raise portable_subtree event "import" attributes {"blob": blob, "secret": secret}
31
+ ```
32
+
33
+ The subtree becomes a child of that pico. The ruleset raises `portable_subtree:imported`, and `portable_subtree:lastImport()` returns the result. Wrangler on the imported pico raises `wrangler:subtree_imported`.
34
+
35
+ ## Things to know
36
+
37
+ - **What the subtree relied on.** Picos often depend on services their ancestors provide: shared rulesets, relationships to a framework's picos, channels set up by a parent. The new parent has to provide them too. For example, import a Manifold app's pico under a Manifold parent, not under a bare root.
38
+ - **The original stays.** Exporting copies; it doesn't remove anything. Delete the source subtree yourself when you no longer need it.
39
+ - **The blob is sensitive.** It holds the subtree's state and capabilities. Treat it, and its secret, like credentials.
40
+
41
+ ## Read more
42
+
43
+ - The [Moving picos](/cookbook/moving_picos/) demo: export a pico and its children from one engine and import them on another.
44
+ - [The design of pico moves](/design/pico-move).