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.
- package/README.md +11 -5
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
- package/demos/echo/com.example.echo.bootstrap.krl +10 -7
- package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
- package/demos/json_query/README.md +11 -0
- package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
- package/demos/json_query/com.example.json_query.krl +162 -0
- package/demos/json_query/try-it.md +5 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
- package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
- package/demos/try-it-order.json +1 -1
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
- package/dist/cli.js +5 -1
- package/dist/engineConfig.js +1 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +44 -12
- package/dist/internalAccess.js +110 -0
- package/dist/oauth/OAuthService.js +172 -10
- package/dist/oauth/acg.js +194 -24
- package/dist/oauth/cimd.js +381 -0
- package/dist/oauth/discovery.js +175 -0
- package/dist/runMcp.js +1 -1
- package/dist/server.js +197 -48
- package/dist/subtreeWrangler.js +8 -5
- package/dist/uiChannelPolicies.js +2 -0
- package/krl/io.picolabs.pds.krl +109 -21
- package/krl/io.picolabs.pico-engine-ui.krl +13 -7
- package/krl/io.picolabs.wrangler.krl +21 -9
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +3 -2
- package/mcp/docs/cookbook/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
- package/mcp/docs/cookbook/child_tasks/README.md +20 -0
- package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
- package/mcp/docs/cookbook/collection/README.md +21 -0
- package/mcp/docs/cookbook/collection/instructions.md +93 -0
- package/mcp/docs/cookbook/echo/README.md +19 -0
- package/mcp/docs/cookbook/echo/instructions.md +59 -0
- package/mcp/docs/cookbook/guard_rules/README.md +22 -0
- package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
- package/mcp/docs/cookbook/json_query/README.md +26 -0
- package/mcp/docs/cookbook/json_query/instructions.md +64 -0
- package/mcp/docs/cookbook/kblog/README.md +60 -0
- package/mcp/docs/cookbook/kblog/instructions.md +102 -0
- package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
- package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
- package/mcp/docs/cookbook/moving_picos/README.md +44 -0
- package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
- package/mcp/docs/cookbook/score_tracker/README.md +19 -0
- package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
- package/mcp/docs/cookbook/secrets/README.md +25 -0
- package/mcp/docs/cookbook/secrets/instructions.md +98 -0
- package/mcp/docs/cookbook/two_picos/README.md +20 -0
- package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
- package/mcp/docs/cookbook/xmlui/README.md +23 -0
- package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
- package/mcp/docs/developing/README.md +28 -0
- package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
- package/mcp/docs/developing/arrays-and-maps.md +77 -0
- package/mcp/docs/developing/converting-time-formats.md +28 -0
- package/mcp/docs/developing/cookies-and-redirects.md +81 -0
- package/mcp/docs/developing/decoding-form-data.md +67 -0
- package/mcp/docs/developing/engine-log-files.md +34 -0
- package/mcp/docs/developing/event-loop.md +77 -0
- package/mcp/docs/developing/events-from-email.md +80 -0
- package/mcp/docs/developing/initializing-entity-variables.md +83 -0
- package/mcp/docs/developing/mcp-ai-tools.md +98 -0
- package/mcp/docs/developing/misconceptions.md +467 -0
- package/mcp/docs/developing/names-and-scope.md +44 -0
- package/mcp/docs/developing/postman.md +159 -0
- package/mcp/docs/developing/querying-another-pico.md +47 -0
- package/mcp/docs/developing/singleton-picos.md +36 -0
- package/mcp/docs/developing/tabular-data.md +67 -0
- package/mcp/docs/developing/tips.md +251 -0
- package/mcp/docs/developing/webhook-signatures.md +56 -0
- package/mcp/docs/developing/workflow.md +106 -0
- package/mcp/docs/exp/README.md +46 -0
- package/mcp/docs/exp/event.md +110 -0
- package/mcp/docs/exp/query.md +94 -0
- package/mcp/docs/lessons/README.md +59 -0
- package/mcp/docs/lessons/events-and-queries.md +247 -0
- package/mcp/docs/lessons/gossip.md +28 -0
- package/mcp/docs/lessons/modules-and-apis.md +270 -0
- package/mcp/docs/lessons/pico-based-systems.md +470 -0
- package/mcp/docs/lessons/pico-state.md +267 -0
- package/mcp/docs/lessons/pico-views.md +290 -0
- package/mcp/docs/lessons/quickstart.md +157 -0
- package/mcp/docs/lessons/relationships.md +530 -0
- package/mcp/docs/lessons/scatter-gather.md +362 -0
- package/mcp/docs/pico-engine.md +7 -5
- package/mcp/docs/pico-overview.md +3 -3
- package/mcp/docs/wrangler/README.md +47 -0
- package/mcp/docs/wrangler/channels.md +235 -0
- package/mcp/docs/wrangler/oauth.md +56 -0
- package/mcp/docs/wrangler/pds.md +423 -0
- package/mcp/docs/wrangler/portable-subtree.md +44 -0
- package/mcp/docs/wrangler/relationships.md +297 -0
- package/mcp/docs/wrangler/wrangler.md +253 -0
- package/mcp/docs/wrangler/xmlui.md +60 -0
- package/mcp/engineClient.js +57 -5
- package/mcp/mcpScopes.js +118 -0
- package/mcp/meshHttp.js +151 -45
- package/mcp/runStdio.js +2 -0
- package/mcp/subtreeTools.js +184 -0
- package/mcp/tryItTools.js +202 -0
- package/package.json +14 -8
- package/public/pico-engine-ui.js +26 -26
- package/src/cli.ts +6 -2
- package/src/engineConfig.ts +5 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -430
- package/src/internalAccess.ts +127 -0
- package/src/oauth/OAuthService.ts +243 -11
- package/src/oauth/acg.ts +289 -25
- package/src/oauth/cimd.ts +508 -0
- package/src/oauth/discovery.ts +233 -0
- package/src/runMcp.ts +3 -1
- package/src/server.ts +252 -52
- package/src/subtreeWrangler.ts +17 -5
- 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).
|