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
@@ -1,7 +1,238 @@
1
- # pico-engine
1
+ # pico-engine — operator guide
2
2
 
3
- Pico engine is a platform for running pico systems written in using the KRL programming language.
3
+ This document is the **canonical operator reference** for running and configuring the pico engine. It ships with the npm package under `public/docs/` and is indexed in [`llms.txt`](llms.txt).
4
4
 
5
- ## How to install it?
5
+ **New to picos?** Read [pico-overview.md](pico-overview.md) — what picos are, why they exist, and the event-query model (`docs/design/pico-overview.md` in the repo).
6
6
 
7
- TODO more
7
+ ## Documentation source of truth
8
+
9
+ | Location | Role |
10
+ |----------|------|
11
+ | **This file** (`packages/pico-engine/public/docs/`) | Authoritative for install, config, security flags, and deployment. Versioned with the engine; what `npx pico-engine` and agents read. |
12
+ | **README** in the same package | Quick start, CLI overview, OAuth, containers — links here for config details. |
13
+ | **`MEMORY.md`** (engine repo) | Maintainer log: rationale, gotchas, env registry — not end-user docs. |
14
+ | **Confluence / wiki** | Optional mirror for Picolab internal use. **Do not treat Confluence as primary:** edit this file in git first, then update Confluence to match (or replace Confluence pages with a short blurb + link to [GitHub `public/docs/pico-engine.md`](https://github.com/Picolab/pico-engine/blob/main/packages/pico-engine/public/docs/pico-engine.md) on `main` or the release tag). |
15
+
16
+ If Confluence and this guide disagree, **trust the repo at the release you run** (`pico-engine --version`).
17
+
18
+ ---
19
+
20
+ ## Quick start
21
+
22
+ ```sh
23
+ npm install -g pico-engine
24
+ pico-engine
25
+ ```
26
+
27
+ Open `http://localhost:3000`. First visit registers a passkey and creates the root pico.
28
+
29
+ Copy the example config and adjust paths:
30
+
31
+ ```sh
32
+ mkdir -p ~/.config/pico-engine
33
+ cp "$(npm root -g)/pico-engine/config.example.json ~/.config/pico-engine/config.json
34
+ # or from a git checkout: packages/pico-engine/config.example.json
35
+ pico-engine
36
+ ```
37
+
38
+ Show which config file the process will use:
39
+
40
+ ```sh
41
+ pico-engine config path
42
+ ```
43
+
44
+ Alternate config file (one file **per engine process**):
45
+
46
+ ```sh
47
+ pico-engine -c /path/to/engine-a.json
48
+ # or
49
+ PICO_ENGINE_CONFIG=/path/to/engine-a.json pico-engine
50
+ ```
51
+
52
+ ---
53
+
54
+ ## Config file vs data directory
55
+
56
+ | | Config | Data (`home`) |
57
+ |---|--------|----------------|
58
+ | **Default path** | `$XDG_CONFIG_HOME/pico-engine/config.json` or `~/.config/pico-engine/config.json` | `~/.pico-engine/` |
59
+ | **Override** | `PICO_ENGINE_CONFIG`, `pico-engine -c` | config JSON `home`, or `PICO_ENGINE_HOME` |
60
+ | **Contains** | Port, public URL, WebAuthn, security flags, policy ceiling | LevelDB mesh (`db/`), ruleset cache, logs |
61
+ | **Delete to reset** | No — keeps operator settings | Yes — **fresh mesh** (picos, passkeys in DB gone) |
62
+
63
+ **Precedence:** defaults → **environment variables** → **config file** → programmatic overrides (tests). If both env and file set `port`, **the file wins**.
64
+
65
+ In **`NODE_ENV=test`**, the config file is ignored unless `PICO_ENGINE_CONFIG` is set (isolated tests).
66
+
67
+ ---
68
+
69
+ ## Config JSON fields
70
+
71
+ Example templates: [`config.example.json`](../../config.example.json), [`config.policy-ceiling.example.json`](../../config.policy-ceiling.example.json), [`config.instances.example/`](../../config.instances.example/).
72
+
73
+ | Field | Type | Description |
74
+ |-------|------|-------------|
75
+ | `home` | string | Data directory (supports `~/…`). Default `~/.pico-engine`. |
76
+ | `port` | number | HTTP listen port. Default `3000`. |
77
+ | `baseUrl` | string | Public origin (no trailing slash): WebAuthn, did:webvh, links. Default `http://localhost:3000`. |
78
+ | `allowSelfSignup` | boolean | Open registration after bootstrap. Default `false` (invite-only). |
79
+ | `allowLocalhostChannelBypass` | boolean | Allow `/c/*` from localhost without passkey (dev MCP, KRL HTTP loops). Default `true`. Set `false` in production behind TLS. |
80
+ | `wildcardSkyRequireBearer` | boolean | Require OAuth bearer on `/sky/*` for channels with unrestricted `*.*` allow rules. Default `false` (1.8 opt-in hardening). |
81
+ | `logToStdout` | boolean | Log to stdout instead of a file. Use on Fargate (set `logToStdout: true` in config). |
82
+ | `logFile` | string | Absolute log path when `logToStdout` is false. Values `stdout`, `-`, or `0` force stdout. |
83
+ | `defaultRootPolicyCeiling` | object | Max channel policy for new root picos (`eventPolicy` / `queryPolicy`). See policy example file. |
84
+ | `globalEventDeny` | array | Extra deny rules applied on **every** ECI before channel policy (e.g. block `engine:secret_ping`). |
85
+ | `globalQueryDeny` | array | Same for queries. |
86
+ | `webauthn.rpId` | string | WebAuthn RP ID (usually hostname without port). |
87
+ | `webauthn.origin` | string | Must match browser URL (scheme + host + port). |
88
+ | `webauthn.rpName` | string | Display name in passkey UI. |
89
+
90
+ Legacy top-level `rpID`, `rpName`, `origin` are still accepted if `webauthn` is omitted.
91
+
92
+ ---
93
+
94
+ ## Environment variables
95
+
96
+ These four env overrides cover config path, data dir, port, and public URL; everything else (WebAuthn, signup, localhost bypass, policy ceiling, logging, …) belongs in the **config file**. Maintainer registry of all env keys: engine repo `MEMORY.md` (Engine environment variables).
97
+
98
+ | Variable | Purpose |
99
+ |----------|---------|
100
+ | `PICO_ENGINE_CONFIG` | Path to config JSON |
101
+ | `PICO_ENGINE_HOME` | Data directory |
102
+ | `PORT` | Listen port (if not in file) |
103
+ | `PICO_ENGINE_BASE_URL` | Public URL |
104
+
105
+ ---
106
+
107
+ ## Multiple engines on one host
108
+
109
+ Give each process its own config with distinct **`home`**, **`port`**, **`baseUrl`**, and matching **`webauthn.origin`**.
110
+
111
+ ```sh
112
+ pico-engine -c ~/.config/pico-engine/engine-a.json # terminal 1
113
+ pico-engine -c ~/.config/pico-engine/engine-b.json # terminal 2
114
+ ```
115
+
116
+ Cursor MCP: separate `mcpServers` entries, each with its own `PICO_ENGINE_CONFIG` pointing at the engine you want.
117
+
118
+ Docker: mount **one config file per service** and **one data volume per service** — never share a `home` volume between two running tasks.
119
+
120
+ ---
121
+
122
+ ## Docker and AWS (summary)
123
+
124
+ Mesh state lives under `home`:
125
+
126
+ | Subdir | Purpose |
127
+ |--------|---------|
128
+ | `db/` | Picos, channels, auth, identity |
129
+ | `rulesets-db/` | Cached ruleset metadata (rebuildable) |
130
+ | `rulesets/` | Compiled ruleset JS |
131
+
132
+ - One writer per data directory (LevelDB).
133
+ - **Fargate:** mount EFS at e.g. `/var/pico-image`, set `home` accordingly, `baseUrl` to public **HTTPS**, `logToStdout: true` in config.
134
+ - Set `allowLocalhostChannelBypass` to **false** on public deployments.
135
+
136
+ Detailed checklists: package **README** § Containers / Fargate.
137
+
138
+ ---
139
+
140
+ ## Wrangler and bundled rulesets
141
+
142
+ **Wrangler** (`io.picolabs.wrangler`) is the pico **OS** — the **preferred layer** for operating on picos. It wraps engine primitives (persistence, channels, ruleset registry, policy) in stable **`wrangler:*` events and shared queries**: children, channels, ruleset install/flush, relationships, discovery, and schema (`picoSchema`, `rulesetSchema`, `channelSchema`). It is installed on every pico with **PDS**, **subscription**, and **pico-engine-ui**.
143
+
144
+ **Use wrangler, not engine escape hatches.** Application rulesets, integrators, and harnesses should raise **`wrangler` events** and call **`wrangler:*` functions** (or the UI / `/sky/*` / mesh MCP surfaces that send those operations). The engine also exposes lower-level **`ctx:*`** actions and owner-only tooling; those exist for wrangler and the platform rulesets to call, not as the everyday API.
145
+
146
+ If something you need **cannot be done through wrangler**:
147
+
148
+ 1. **Red flag — you may be out of bounds.** Lifecycle and mesh structure belong in wrangler (or in a domain framework such as Manifold built *on* wrangler), not in ad hoc `ctx:` calls or custom engine hooks from app KRL.
149
+ 2. **Possible bug or missing OS feature.** If the gap is real OS work (a new child type, channel operation, install path, …), [open an issue](https://github.com/Picolab/pico-engine/issues) on **pico-engine** and describe the wrangler-shaped event or query you expected — not a request to bless more direct `ctx` use.
150
+
151
+ **How to interact:** developer UI (Rulesets, Channels, About), **`wrangler:*` on `/sky/event`** where channel policy allows, **`wrangler:picoQuery`** on family channels, and the generated [wrangler API doc](rulesets/io.picolabs.wrangler.md).
152
+
153
+ **Optional** rulesets ship in the same `krl/` directory but are not auto-installed on every pico:
154
+
155
+ | Ruleset | When to install |
156
+ |---------|-----------------|
157
+ | [io.picolabs.oauth](rulesets/io.picolabs.oauth.md) | **Root pico only** — require OAuth bearer on most `/sky/*` traffic (mesh lock) |
158
+ | [io.picolabs.portable_subtree](rulesets/io.picolabs.portable_subtree.md) | Portable subtree export/import (e.g. identity-aware move) |
159
+
160
+ Install optional rulesets from the **Rulesets** tab (URL like `https://your-engine/krl/io.picolabs.oauth.krl`) or send `wrangler:install_ruleset_request`.
161
+
162
+ **Generated API docs** (events, queries, `@example` from KRL annotations) live under **[rulesets/](rulesets/README.md)** — notably [wrangler](rulesets/io.picolabs.wrangler.md). Refresh in a git checkout: `npm run check:krl-schema-samples` then **`npm run generate:llms`** (copies samples into `public/docs/rulesets/`).
163
+
164
+ ---
165
+
166
+ ## Manifold (mesh framework)
167
+
168
+ Above wrangler sits **[Manifold](https://github.com/Picolab/manifold-api)** — KRL rulesets that define a **personal mesh**: owner, Manifold hub, **things** (devices, vehicles, objects), **communities** (groups of things), tag and skills registries, and centralized notifications. Manifold uses **wrangler** for all lifecycle (`manifold:create_thing` delegates to `wrangler:new_child_request`, and so on); app code should call **`manifold:*` and domain events**, not `ctx:`.
169
+
170
+ Manifold is **not** one product. It is the shared platform for many meshes, for example:
171
+
172
+ - **Fuse-like connected car** networks (owners, vehicles, shared access)
173
+ - **Household / personal IoT** with things and communities
174
+ - **SafeAndMine**, **Home Assistant**, and other integrators shipped from manifold-api
175
+ - **Sensor or industrial monitoring** (separate repos install bootstrap rulesets on the Manifold pico)
176
+
177
+ Install **`io.picolabs.manifold_bootstrap`** on the engine root to stand up the graph; domain repos add their own rulesets on the Manifold child.
178
+
179
+ **Documentation (separate repo):**
180
+
181
+ - Overview: [docs/Manifold.md](https://github.com/Picolab/manifold-api/blob/main/docs/Manifold.md)
182
+ - Agent index: [docs/llms.txt](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt)
183
+ - Generated ruleset APIs: [docs/rulesets/](https://github.com/Picolab/manifold-api/tree/main/docs/rulesets) (e.g. [manifold_pico](https://github.com/Picolab/manifold-api/blob/main/docs/rulesets/io.picolabs.manifold_pico.md))
184
+
185
+ ---
186
+
187
+ ## Security and policy (1.8)
188
+
189
+ - **Deny overrides permit** on channel policies (pico-framework 0.8.2+).
190
+ - **Policy ceiling:** parent can cap child channel policies; optional `defaultRootPolicyCeiling` on the root.
191
+ - **Wildcard channels:** opt-in `wildcardSkyRequireBearer` so wide `/sky/*` access requires a validated bearer.
192
+ - **Channel policy audit:** [channel-policy-audit-2026-10.md](https://github.com/Picolab/pico-engine/blob/main/docs/design/channel-policy-audit-2026-10.md) (repo; summary in [1.8.0 release notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md)).
193
+
194
+ Owner UI uses the **UI channel** (passkey). Automation uses **OAuth** on `/sky/*` and narrow channels — see README § OAuth.
195
+
196
+ ---
197
+
198
+ ## HTTP surfaces
199
+
200
+ | Path | Auth | Use |
201
+ |------|------|-----|
202
+ | `/` | Browser | Developer UI |
203
+ | `/c/*` | Passkey session (localhost bypass optional) | Developer UI (browser). **Discouraged** for automation and third-party apps — use `/sky/*` or mesh MCP instead. |
204
+ | `/sky/*` | Channel policy ± OAuth bearer | Events, queries, integrators |
205
+ | `/mcp/:eci` | OAuth bearer | Mesh MCP (Streamable HTTP) |
206
+ | `/auth/*` | WebAuthn flows | Registration, login |
207
+
208
+ Local dev MCP: `pico-engine mcp --stdio` — not exposed on hosted load balancers; see [1.8 plan § MCP](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.md) (deployment table).
209
+
210
+ ---
211
+
212
+ ## Agents and KRL authoring
213
+
214
+ - **`krl-check`** on ruleset files before install.
215
+ - **Dev MCP** (stdio): validate, install, flush, raise, query — same mesh as the UI when `PICO_ENGINE_HOME` / config match.
216
+ - **Docs for LLMs:** [`llms.txt`](llms.txt), [`llms-full.txt`](llms-full.txt), [`openapi.yaml`](openapi.yaml). Regenerate after doc edits: `npm run generate:llms` at repo root.
217
+
218
+ ---
219
+
220
+ ## Troubleshooting
221
+
222
+ | Symptom | Check |
223
+ |---------|--------|
224
+ | Passkey fails | `baseUrl` / `webauthn.origin` match browser URL; HTTPS in production |
225
+ | “Not allowed by channel policy” | Channel event/query policy; ceiling; global deny lists |
226
+ | Install/flush errors in UI | Event-wait returns `events` with `ruleset_install_failed` / `ruleset_flush_failed` and line/col in `errors` |
227
+ | LevelDB LOCK on startup | Unclean shutdown; stop all tasks using the volume; engine may remove stale LOCK |
228
+ | Empty mesh after deploy | Fargate EBS vs EFS — use persistent volume for `home` |
229
+
230
+ Logs: default `$home/pico-engine.log`, or stdout when configured. Engine logs **`txnError`** at error level for ruleset compile failures (includes line/col when available).
231
+
232
+ ---
233
+
234
+ ## Related docs
235
+
236
+ - [Pico overview / philosophy](pico-overview.md) · [Bundled rulesets (wrangler, PDS, …)](rulesets/README.md) · [Manifold mesh framework](https://github.com/Picolab/manifold-api/blob/main/docs/llms.txt) · [KRL manual](krl/README.md)
237
+ - Package [README](../../README.md) — OAuth, authentication, full container checklist
238
+ - Release [1.8.0 notes](https://github.com/Picolab/pico-engine/blob/main/docs/release/1.8.0.md) — what changed in this line
@@ -0,0 +1,117 @@
1
+ # Picos: what they are, what they enable, and what they are for
2
+
3
+ **Status:** draft (2026-09-24)
4
+ **Audience:** anyone arriving at this repo — contributors, students, integrators — who needs the model in their head before reading the other design docs.
5
+ **Sources:** the design docs in this folder and `MEMORY.md`; the `manifold-api`, `sensor-network`, and `MCPforEXP` repos; the Picolabs wiki; and the picos-tagged posts on windley.com (2013–2026). Links at the end.
6
+
7
+ ---
8
+
9
+ ## 1. What picos are
10
+
11
+ A **pico** (persistent compute object) is a small, general-purpose, always-online computer that stands in for one entity: a person, a place, a device, an organization, a group, a concept, even a pothole. It has a unique identity, keeps its own state, runs its own programs, and talks to other picos by exchanging events and answering queries. Networks of picos model the world — one addressable actor per thing we care about.
12
+
13
+ Picos are **actors** in the [actor-model](https://en.wikipedia.org/wiki/Actor_model) sense. In response to a message a pico may send messages to other picos, create other picos, and change its internal state, which affects how it handles the next message. Picos share nothing except messages; one pico cannot see or touch another's state.
14
+
15
+ Three kinds of persistence distinguish picos from most other programming models:
16
+
17
+ | Property | Meaning |
18
+ |----------|---------|
19
+ | **Persistent identity** | A pico exists with one stable identity from creation until it is explicitly deleted. Since 1.6 that identity is a portable `did:webvh` that survives moving between engines. |
20
+ | **Persistent state** | A pico's state lives inside it, isolated from every other pico, and is available to any rule that runs there. No external database. |
21
+ | **Persistent availability** | Once created, a pico is always on and ready for events and queries. Restarting the engine changes nothing about what picos exist or know. |
22
+
23
+ ### Anatomy of a pico
24
+
25
+ | Part | What it is |
26
+ |------|------------|
27
+ | **Rulesets and event bus** | Behavior is installed as KRL rulesets, loaded by URL and compiled to JavaScript. A rule is event-condition-action: `select when` an event expression matches, evaluate a condition, act, then a postlude that updates state and raises further events. Every incoming event is raised on the pico's internal bus; a salience graph routes it to listening rules, so installing a ruleset subscribes its rules automatically. |
28
+ | **Event-query API** | Not RESTful. The **Sky Event API** delivers events; the **Sky Cloud/Query API** calls shared functions. It is a *meta-API*: a pico's concrete API is whatever its installed rulesets provide, and it can change over the pico's life. |
29
+ | **State: entity variables and PDS** | `ent:` variables are scoped to each ruleset (a closure over its data). The **Pico Data Store** (default since 1.4) is the shared data plane on every pico — profile, namespaced general data, per-ruleset settings — written by `pds` events, read by shared functions. |
30
+ | **Channels (ECIs)** | As many channels as a pico needs, each with an Event Channel Identifier and its own event/query **policy**. Channels are non-correlatable addresses and the local authorization gate. A `discovery` channel on every pico lets integrators learn what it can do. |
31
+ | **Relationships** | Pairwise, bidirectional, policy-gated connections between picos (*subscriptions* before 1.6.2). They form the heterarchical graph applications run on, independent of the parent/child tree and of which engine hosts each pico. |
32
+ | **Parent/child tree + Wrangler** | Every pico except a root has a parent, which installs and initializes it; control of a root implies control of its subtree. **Wrangler**, the pico OS on every pico, exposes lifecycle, channels, and relationships as KRL functions and events. |
33
+ | **Identity** | Three planes: a human unlocks their **root pico** with a passkey (the root is the person's actor on the mesh); picos identify themselves to each other with **DIDs** (`did:webvh` per pico, `did:peer` per relationship, DIDComm across meshes); outside software reaches a mesh with **OAuth** tokens on `/sky/*`. |
34
+
35
+ ### Where picos run
36
+
37
+ Picos live in a **pico engine**, an open-source Node.js runtime built on `pico-framework` (lifecycle, channels, LevelDB persistence) and `select-when` (event-expression matching) with a KRL compiler on top. One engine hosts many picos and, since 1.5, many independent **meshes** (a root pico and its descendants) belonging to different owners. Picos on different engines form relationships as easily as picos on the same engine; the engines need no arrangement between them. The engine runs on a Raspberry Pi and on Fargate.
38
+
39
+ The stack above the engine is strictly layered, and the layering is a design rule: engine and wrangler stay domain-agnostic; Manifold and community rulesets supply the vocabulary (owner, thing, community, borrower).
40
+
41
+ ```
42
+ engine ← primitives: picos, channels, policy, persistence, DID keys, passkeys, OAuth
43
+ wrangler ← the OS: children, channels, relationships, discovery
44
+ manifold ← a framework for pico meshes: owner, things, communities, registries, notifications
45
+ mesh apps ← sensor-network, SafeAndMine, Fuse-style apps
46
+ ```
47
+
48
+ ### Lineage
49
+
50
+ Picos grew out of the Kynetx rules engine (2008) and its "personal cloud" era: CloudOS, SquareTag, Fuse (a production connected-car platform, 2013–2015, hundreds of customers and over a thousand devices), and a guard-tour system. The Node rewrite (2017) made the engine small and fast; 1.0 (2021) made it modular; 1.4 added PDS by default; 1.5 (July 2026) brought passkeys and OAuth into the engine; 1.6 (August 2026) shipped DID-based identity and relationships. The motivation has not changed: an Internet of Things that is decentralized, heterarchical, and interoperable — an alternative to the "CompuServe of Things," where people rent connected devices from vendors in the middle.
51
+
52
+ ---
53
+
54
+ ## 2. What pico features enable
55
+
56
+ The value is the combination: every entity gets a **closure over identity, data, and behavior**.
57
+
58
+ | Feature | What it enables |
59
+ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
60
+ | **Persistent identity** (`did:webvh`, channels) | Relationships that outlive restarts and moves; reputation and history; credentials with a durable subject; revocable delegation; a lifecycle that follows the thing across owners. Why SPIFFE was set aside: it names replaceable processes; picos are actors that last. |
61
+ | **Persistent state and availability** (entity vars, PDS) | Databaseless programming; the running system *is* the design, visible live in the developer UI. Data control at the ruleset grain: delete the trip service before transferring a vehicle, keep the maintenance records. Twins keep working while the owner is offline. |
62
+ | **Rules on an event bus** | Each rule is a microservice for one entity. Functionality accretes — install a ruleset and its rules start listening. Correlation ids, scatter-gather, guard rules, scheduled retries, and routed error events make failure-tolerant asynchrony the default. |
63
+ | **Event-query meta-API + discovery** | A pico's API is discoverable at runtime. Home Assistant turns discovery bindings into devices and services; the MCP interface turns them into LLM tools, gated to the rulesets actually installed. |
64
+ | **Channels with policy** | Capability-style security: an ECI is permission to do what its policy allows and nothing more. Separate channels prevent correlation, scope webhooks to one endpoint, and let discovery filter bindings per caller. |
65
+ | **Typed, pairwise relationships** | Heterarchical graphs across the tree and across engines. Rights are *relationships*, not attributes: a fleet can have two owners, a truck can be lent with attenuated rights, a community can accept members from other meshes. The **introduction pattern** — an existing relationship brokers a new one — generalizes to delegation, transfer, and ReBAC. |
66
+ | **Tree + Wrangler** | Programmatic lifecycle: picos create, initialize, and delete picos; prototypes stamp out configured children. Admin rights follow the tree; everything else is conferred by policy. |
67
+ | **Actor concurrency** | Lock-free, isolated, location-transparent. Applications shard naturally — one pico per section, sensor, vehicle — and scale by adding engines. A laptop replayed 44,504 registration events into 8,000+ section picos at 21 events/sec. |
68
+ | **Three-plane identity** | Self-sovereign meshes: no central identity provider, no password database; strangers on different engines trust each other by resolving DIDs, with no federation. Integrators get scoped, revocable OAuth access without becoming the pico. |
69
+ | **Substitutable, small hosting** | A Pi, a community server, or a cloud, with picos movable between them. Compute moves toward the data, and a vendor's cloud shutting down does not brick the thing. |
70
+
71
+ ---
72
+
73
+ ## 3. Five use cases
74
+
75
+ | Use case | Picos | Relationships | Status |
76
+ |----------|-------|---------------|--------|
77
+ | LoRaWAN sensor network | owner, Manifold hub, sensor communities, sensor things | community ↔ thing; hub ↔ community; Home Assistant via OAuth | Running at the cabin |
78
+ | Connected vehicles, transferable twins | owner, fleet, vehicle | FleetOwner per owner; vehicle ↔ mechanic, insurer, borrower | Fuse shipped 2014; DID-era transfer designed |
79
+ | Personal inventory and lost-and-found | owner, things, communities, tag and skills registries | thing ↔ community; tag → thing via registry | Manifold on 1.5+; tag-scan path in progress |
80
+ | AI that works for the owner | root or household pico and children as memory and event sources | pico ↔ model via webhook or callback; later a local model | Webhook pattern now; `llm:*` designed |
81
+ | High-fan-out institutional systems | institution, index picos, tours, locations, reports; or one pico per course section | personal cloud ↔ institution; collection → members | Guard tour delivered 2014; registration proof 2017 |
82
+
83
+ ### 3.1 A LoRaWAN sensor network
84
+
85
+ Battery-powered Dragino sensors in a pump house, a crawl space, a deck, and a beehive report over the Helium network. Each sensor is a **thing pico** in a **sensor community pico** under the owner's Manifold hub. Helium posts each heartbeat to a channel on the sensor's pico; a router ruleset decodes the payload and raises `sensor:new_readings`; a thresholds ruleset raises `sensor:threshold_violation`; the community raises `manifold:add_notification`, and Manifold fans the alert out to whatever the owner enabled (inbox, SMS, Prowl, Home Assistant). Home Assistant connects over OAuth and renders the mesh as devices — history, dashboards, automations — with no custom UI. Picos contribute one actor per sensor with its own decoding, thresholds, and history; communities that own bootstrap and aggregation; a notification platform no domain ruleset reimplements; and a way to admit a machine (the Helium webhook) into an OAuth-locked mesh by exempting one narrow channel. Adding a sensor type is one router ruleset.
86
+
87
+ ### 3.2 Connected vehicles and transferable digital twins
88
+
89
+ Fuse gave every vehicle a pico fed by an OBD-II device — trips, fuel, maintenance, diagnostic codes, alerts, each a set of rules in the vehicle pico — with an owner pico and a fleet pico above. Ownership was a **relationship** (`FleetOwner`), so two owners were two relationships, and a new owner was added through the introduction pattern. The design docs carry this forward: a vehicle's relationships with manufacturer, mechanic, insurer, borrower, and DMV are one mechanism with different roles and Rx policies. When Phil sells his truck to Dave on another engine, the truck's `did:webvh` stays the same, parent and community links move to Dave's mesh, and the battery-health service relationship survives via DID rotation. Trip data can be deleted before transfer; maintenance records stay with the vehicle. The twin's identity is bound to the vehicle, not to any owner.
90
+
91
+ ### 3.3 Personal inventory, tags, and lost-and-found
92
+
93
+ SquareTag, and now Manifold with SafeAndMine, gives a person a mesh of **thing picos** for the objects they care about — a backpack, a bike, a furnace — grouped into communities. Each thing carries skills: SafeAndMine registers QR/NFC tags in the tag registry and shows owner contact information to a finder who scans one; Journal records notes such as filter changes. Things are created, tagged, and annotated through Home Assistant or through a conversational interface: an MCP server exposes Manifold operations as tools, and skill-gating shows the model only the tools whose rulesets are installed on the pico at hand, offering to install what is missing. Every thing has its own API, skills are installed per thing at runtime, a thing can belong to several communities, and the data stays in the owner's mesh rather than a vendor's account.
94
+
95
+ ### 3.4 AI that works for the owner
96
+
97
+ Picos already have what an AI integration needs: persistent identity, owned state, and an event-driven interface. The progression starts shallow — a pico fires an event, an external routine reasons and posts a response event back — then moves to KRL actions that call a model with a callback event, then to the model using pico queries as tools so that the **pico is the memory**, and finally to the model raising events into the pico graph to make things happen. A household pico gives a model a cross-domain view over its children (car, sensors, calendar) while the hierarchy encodes the privacy boundary. The local-model design adds `llm:complete`, `llm:extract`, `llm:classify`, and `llm:summarize` as KRL primitives bounded by channel policy, with the rule that the model *proposes* and KRL *commits*. Fuse's bare alerts are the motivating example: a diagnostic code enriched with context and a recommendation is what drivers needed.
98
+
99
+ ### 3.5 High-fan-out institutional systems
100
+
101
+ The **guard tour** system modeled an institution, tours, locations, and reports as separate picos, with index picos mapping identifiers to channels; guards and managers used their own personal clouds with a guard-tour ruleset installed — no accounts in the tour system — plus temporary channels for the duration of a tour. **BYU priority registration** modeled each of 5,393 course sections as a pico keeping its own roster; replaying two days of add/drop requests showed that an actor per entity absorbs a surge without contention. The pattern: many entities with independent state and bursty activity get one pico each, plus collection picos for grouping, and people participate through their own picos rather than an account the institution owns.
102
+
103
+ ---
104
+
105
+ ## Open work
106
+
107
+ Moving picos between engines ([pico-move.md](./pico-move.md)), pico-level schemas ([pico-schemas.md](./pico-schemas.md)), the `peer` relationship type and ReBAC in community rulesets ([pico-relationships.md](./pico-relationships.md)), delegated admin ([delegated-admin-relationship.md](./delegated-admin-relationship.md)), local LLM primitives ([pico-llm-capabilities.md](./pico-llm-capabilities.md)), and the channel-policy ceiling and pico mirrors (`MEMORY.md` roadmap).
108
+
109
+ ## Sources
110
+
111
+ **Actor model:** [Actor model](https://en.wikipedia.org/wiki/Actor_model) — general overview; Hewitt, Bishop and Steiger, *A Universal Modular ACTOR Formalism for Artificial Intelligence* (IJCAI 1973) — the origin; [Agha, *Actors: A Model of Concurrent Computation in Distributed Systems*](https://dspace.mit.edu/handle/1721.1/6952) (MIT AITR-844, 1985) — the canonical treatment.
112
+
113
+ **Repos and docs:** this folder and `MEMORY.md`; [manifold-api](https://github.com/Picolab/manifold-api) (`README.md`, `docs/Manifold.md`, `docs/Managing_PDS.md`); [sensor-network](https://github.com/windley/sensor-network); [MCPforEXP](https://github.com/picolab/MCPforEXP).
114
+
115
+ **Confluence documentation** — the [Pico Labs developer site](https://picolabs.atlassian.net/wiki/spaces/docs/overview) is the reference manual for everything above. Start here: [Pico Engine Quickstart](https://picolabs.atlassian.net/wiki/spaces/docs/pages/19791878) · [Pico Programming Lessons](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1185969). Engine and Wrangler: [Pico Engine](https://picolabs.atlassian.net/wiki/spaces/docs/pages/6356996) · [Wrangler](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1686929547) · [Picos API](https://picolabs.atlassian.net/wiki/spaces/docs/pages/761593879) · [Managing Channels](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403288) · [Managing Pico Lifecycle](https://picolabs.atlassian.net/wiki/spaces/docs/pages/11403290). KRL: [KRL Manual](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189890) · [Libraries](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189596) · [KRL Cookbook](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1190497). Identity: [Identity System](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3962044419) · [DIDs — Pico Identity](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4033413122) · [Relationships](https://picolabs.atlassian.net/wiki/spaces/docs/pages/4032102406). Platform: [Manifold](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907190800) · [Pico Data Store](https://picolabs.atlassian.net/wiki/spaces/docs/pages/3907289100).
116
+
117
+ **Blog (windley.com, tag: picos):** [Fundamental Features of Persistent Compute Objects](https://www.windley.com/archives/2013/10/fundamental_features_of_persistent_compute_objects.shtml) · [Pico APIs: Events and Queries](https://www.windley.com/archives/2013/12/pico_apis_events_and_queries.shtml) · [Complex Pico Structures: Guard Tours](https://www.windley.com/archives/2014/01/complex_pico_structures_guard_tours.shtml) · [Fuse as a Microservice Architecture](https://www.windley.com/archives/2014/07/fuse_as_a_microservice_architecture.shtml) · [Fuse with Two Owners](https://www.windley.com/archives/2014/10/fuse_with_two_owners.shtml) · [Reactive Programming with Picos](https://www.windley.com/archives/2015/11/reactive_programming_with_picos.shtml) · [Reactive Programming Patterns: Examples from Fuse](https://www.windley.com/archives/2016/04/reactive_programming_patterns_examples_from_fuse.shtml) · [Using Picos for BYU's Priority Registration](https://www.windley.com/archives/2017/01/using_picos_for_byus_priority_registration.shtml) · [Announcing Pico Engine 1.0](https://www.windley.com/archives/2021/02/announcing_pico_engine_10.shtml) · [Persistence, Programming, and Picos](https://www.windley.com/archives/2021/02/persistence_programming_and_picos.shtml) · [Ten Reasons to Use Picos](https://www.windley.com/archives/2021/07/ten_reasons_to_use_picos_for_your_next_decentralized_programming_project.shtml) · [Alternatives to the CompuServe of Things](https://www.windley.com/archives/2021/07/alternatives_to_the_compuserve_of_things.shtml) · [Monitoring Temperatures in a Remote Pump House](https://www.windley.com/archives/2023/03/monitoring_temperatures_in_a_remote_pump_house_using_lorawan.shtml) · [Building a Conversational Interface for Manifold](https://www.windley.com/archives/2026/04/building_a_conversational_interface_for_manifold_with_mcp_and_picos.shtml) · [AI Integration in Picos Starts with Events](https://www.windley.com/archives/2026/06/ai_integration_in_picos_starts_with_events.shtml) · [Manifold API and Sensor Network](https://www.windley.com/archives/2026/06/manifold_api_and_sensor_network_two_new_repos.shtml) · [Identity for the Pico Engine](https://www.windley.com/archives/2026/07/identity_for_the_pico_engine.shtml) · [Why Not SPIFFE for Pico Identity?](https://www.windley.com/archives/2026/08/why_not_spiffe_for_pico_identity.shtml) · [Moving My Sensor Network onto Manifold](https://www.windley.com/archives/2026/09/moving_my_sensor_network_onto_manifold.shtml).
@@ -1,3 +1,5 @@
1
1
  # Persistent Compute Objects
2
2
 
3
- TODO
3
+ The philosophy and model doc is **[pico-overview.md](pico-overview.md)** (source: `docs/design/pico-overview.md` in the repo; copied into `public/docs/` by `npm run generate:llms`).
4
+
5
+ Legacy wiki copy: [Persistent Compute Objects on Confluence](https://picolabs.atlassian.net/wiki/spaces/docs/pages/1189992) — prefer the repo overview when they differ.
@@ -0,0 +1,25 @@
1
+ # Bundled rulesets (generated docs)
2
+
3
+ Markdown here is copied from `tools/krl-schema/samples/` when you run **`npm run generate:llms`** at the repo root. Sources are the annotated KRL under `packages/pico-engine/krl/`. To regenerate samples from KRL: **`npm run check:krl-schema-samples`** (CI) or `node tools/krl-schema/cli.js -f markdown path/to/ruleset.krl`.
4
+
5
+ ## OS layer (every pico)
6
+
7
+ Installed on the root pico and on each new child automatically.
8
+
9
+ | Ruleset | Doc |
10
+ |---------|-----|
11
+ | **io.picolabs.wrangler** | [wrangler](io.picolabs.wrangler.md) — **pico OS**; the supported API for mesh lifecycle (not raw `ctx:*`). If an operation is missing here, treat it as out-of-bounds or [file an engine issue](https://github.com/Picolab/pico-engine/issues). |
12
+ | **io.picolabs.pds** | [pds](io.picolabs.pds.md) — profile and shared namespaced data |
13
+ | **io.picolabs.subscription** | [subscription](io.picolabs.subscription.md) — relationships to other picos |
14
+ | **io.picolabs.pico-engine-ui** | [pico-engine-ui](io.picolabs.pico-engine-ui.md) — developer UI channel |
15
+
16
+ ## Optional (install when needed)
17
+
18
+ Shipped under `/krl/` on your engine; install from the Rulesets tab or `wrangler:install_ruleset_request` with the ruleset URL.
19
+
20
+ | Ruleset | Doc | Notes |
21
+ |---------|-----|--------|
22
+ | **io.picolabs.oauth** | [oauth](io.picolabs.oauth.md) | **Root pico only** — optional mesh-wide OAuth on `/sky/*` |
23
+ | **io.picolabs.portable_subtree** | [portable_subtree](io.picolabs.portable_subtree.md) | Portable export/import of subtrees (identity-aware move) |
24
+
25
+ Application rulesets (Manifold, your apps) are not bundled; install their KRL URLs like any other ruleset.
@@ -0,0 +1,71 @@
1
+ # io.picolabs.oauth
2
+
3
+ Optional mesh-level OAuth. Install on the root pico to require Bearer tokens on external /sky/*
4
+ for this mesh (except channels tagged mesh-oauth-exempt or didcomm+ingress), and to hold
5
+ per-mesh OAuth configuration (apps, consent policy, defaults).
6
+ Webhook Client Credentials (per channel, oauth-webhook tag) and app Authorization Code grants
7
+ coexist here. Not installed by default.
8
+
9
+ use module io.picolabs.oauth alias oauth
10
+
11
+ *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.*
12
+
13
+ **Queries:** [meshEnabled](#meshenabled--boolean) · [meshRequiresOAuth](#meshrequiresoautheci--boolean) · [channelStatus](#channelstatuseci--map) · [createChannelSecret](#createchannelsecreteci--map) · [revokeChannelSecret](#revokechannelsecreteci--map) · [revokeTokens](#revoketokenseci--map)
14
+
15
+ ## Queries
16
+
17
+ ### `meshEnabled()` → Boolean
18
+
19
+ True when this ruleset is installed on the pico. Its presence is the mesh's opt-in to OAuth.
20
+
21
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/meshEnabled`, or `<alias>:meshEnabled()` from KRL with `use module io.picolabs.oauth alias <alias>`
22
+
23
+ ### `meshRequiresOAuth(eci)` → Boolean
24
+
25
+ True when external /sky/* requests on this channel need a Bearer token: the mesh root has io.picolabs.oauth installed and the channel is not tagged mesh-oauth-exempt or didcomm+ingress.
26
+
27
+ | Parameter | Type | Required | Default | Description |
28
+ |-----------|------|----------|---------|-------------|
29
+ | `eci` | String | yes | | channel to check |
30
+
31
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/meshRequiresOAuth?eci=…`, or `<alias>:meshRequiresOAuth(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
32
+
33
+ ### `channelStatus(eci)` → Map
34
+
35
+ OAuth webhook status of a channel: whether it is eligible (tagged oauth-webhook), whether OAuth is enabled on it, and whether a client secret exists. Includes a reason when the channel is not eligible or not found.
36
+
37
+ | Parameter | Type | Required | Default | Description |
38
+ |-----------|------|----------|---------|-------------|
39
+ | `eci` | String | yes | | channel to inspect |
40
+
41
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/channelStatus?eci=…`, or `<alias>:channelStatus(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
42
+
43
+ ### `createChannelSecret(eci)` → Map
44
+
45
+ Create (or replace) the Client Credentials secret for a webhook channel and return it. The secret is returned only here; the engine stores a hash, so save it now. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
46
+
47
+ | Parameter | Type | Required | Default | Description |
48
+ |-----------|------|----------|---------|-------------|
49
+ | `eci` | String | yes | | webhook channel (tagged oauth-webhook); also the client_id |
50
+
51
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/createChannelSecret?eci=…`, or `<alias>:createChannelSecret(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
52
+
53
+ ### `revokeChannelSecret(eci)` → Map
54
+
55
+ Revoke a webhook channel's client secret so it can no longer obtain tokens. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
56
+
57
+ | Parameter | Type | Required | Default | Description |
58
+ |-----------|------|----------|---------|-------------|
59
+ | `eci` | String | yes | | webhook channel |
60
+
61
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/revokeChannelSecret?eci=…`, or `<alias>:revokeChannelSecret(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`
62
+
63
+ ### `revokeTokens(eci)` → Map
64
+
65
+ Revoke all access tokens issued for a channel, without removing its secret. Only works for a channel on this pico or one of its descendants. Changes state despite being a query.
66
+
67
+ | Parameter | Type | Required | Default | Description |
68
+ |-----------|------|----------|---------|-------------|
69
+ | `eci` | String | yes | | channel whose tokens to revoke |
70
+
71
+ **Call:** `GET /sky/query/<eci>/io.picolabs.oauth/revokeTokens?eci=…`, or `<alias>:revokeTokens(eci)` from KRL with `use module io.picolabs.oauth alias <alias>`