pico-engine 1.6.4 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +13 -8
  2. package/dist/RulesetRegistryLoaderFs.js +14 -2
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/channelIdentityPolicy.js +22 -0
  6. package/dist/cli.js +104 -69
  7. package/dist/engineConfig.js +280 -0
  8. package/dist/identity/IdentityService.js +90 -0
  9. package/dist/identity/crossPico.js +24 -8
  10. package/dist/identity/didoModule.js +80 -18
  11. package/dist/identity/establishSubscription.js +2 -2
  12. package/dist/identity/identityPortable.js +92 -0
  13. package/dist/identity/index.js +10 -1
  14. package/dist/identity/localPeerReconcile.js +65 -0
  15. package/dist/identity/peerDid4.js +175 -0
  16. package/dist/identity/peerDid4Create.js +90 -0
  17. package/dist/identity/portableExportPrepare.js +196 -0
  18. package/dist/identity/portableMove.js +87 -0
  19. package/dist/identity/skyIntro.js +6 -3
  20. package/dist/identity/skyProtocol.js +26 -1
  21. package/dist/identity/skyRotation.js +121 -0
  22. package/dist/identity/store.js +5 -1
  23. package/dist/identity/subscriptionEntSync.js +72 -0
  24. package/dist/identity/veramoDidComm.js +41 -2
  25. package/dist/identity/webvh.js +4 -2
  26. package/dist/identity/webvhRelocation.js +115 -0
  27. package/dist/index.js +82 -22
  28. package/dist/logging.js +8 -12
  29. package/dist/oauth/OAuthService.js +6 -2
  30. package/dist/policyConfigFromJson.js +112 -0
  31. package/dist/runMcp.js +27 -0
  32. package/dist/server.js +56 -24
  33. package/dist/subtreeWrangler.js +180 -0
  34. package/dist/uiChannelPolicies.js +15 -0
  35. package/krl/io.picolabs.oauth.krl +41 -2
  36. package/krl/io.picolabs.pds.krl +131 -10
  37. package/krl/io.picolabs.pico-engine-ui.krl +209 -21
  38. package/krl/io.picolabs.portable_subtree.krl +97 -0
  39. package/krl/io.picolabs.subscription.krl +180 -72
  40. package/krl/io.picolabs.wrangler.krl +296 -57
  41. package/mcp/devResources.js +118 -0
  42. package/mcp/devTools.js +351 -0
  43. package/mcp/engineClient.js +133 -0
  44. package/mcp/meshHttp.js +137 -0
  45. package/mcp/meshTools.js +189 -0
  46. package/mcp/runStdio.js +34 -0
  47. package/mcp/schemaToZod.js +56 -0
  48. package/package.json +20 -8
  49. package/public/docs/_sidebar.md +2 -1
  50. package/public/docs/llms-full.txt +479 -0
  51. package/public/docs/llms.txt +37 -0
  52. package/public/docs/openapi.yaml +78 -0
  53. package/public/docs/pico-engine.md +235 -4
  54. package/public/docs/pico-overview.md +117 -0
  55. package/public/docs/pico.md +3 -1
  56. package/public/docs/rulesets/README.md +25 -0
  57. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  58. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  59. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  60. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  61. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  62. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  63. package/public/pico-engine-ui.css +1 -1
  64. package/public/pico-engine-ui.js +28 -26
  65. package/src/RulesetRegistryLoaderFs.ts +18 -3
  66. package/src/auth/cookies.ts +34 -0
  67. package/src/auth/index.ts +7 -0
  68. package/src/channelIdentityPolicy.ts +29 -0
  69. package/src/cli.ts +68 -37
  70. package/src/engineConfig.ts +345 -0
  71. package/src/identity/IdentityService.ts +189 -1
  72. package/src/identity/crossPico.ts +57 -8
  73. package/src/identity/didoModule.ts +140 -23
  74. package/src/identity/establishSubscription.ts +2 -2
  75. package/src/identity/identityPortable.ts +153 -0
  76. package/src/identity/index.ts +14 -0
  77. package/src/identity/localPeerReconcile.ts +97 -0
  78. package/src/identity/peerDid4.ts +197 -0
  79. package/src/identity/peerDid4Create.ts +121 -0
  80. package/src/identity/portableExportPrepare.ts +302 -0
  81. package/src/identity/portableMove.ts +193 -0
  82. package/src/identity/skyIntro.ts +11 -11
  83. package/src/identity/skyProtocol.ts +46 -0
  84. package/src/identity/skyRotation.ts +211 -0
  85. package/src/identity/store.ts +5 -1
  86. package/src/identity/subscriptionEntSync.ts +97 -0
  87. package/src/identity/veramoDidComm.ts +52 -2
  88. package/src/identity/webvh.ts +4 -4
  89. package/src/identity/webvhRelocation.ts +167 -0
  90. package/src/index.ts +119 -25
  91. package/src/logging.ts +8 -14
  92. package/src/oauth/OAuthService.ts +11 -3
  93. package/src/policyConfigFromJson.ts +131 -0
  94. package/src/runMcp.ts +30 -0
  95. package/src/server.ts +79 -26
  96. package/src/subtreeWrangler.ts +278 -0
  97. package/src/uiChannelPolicies.ts +15 -0
  98. package/krl/io.picolabs.did-o.krl +0 -349
@@ -0,0 +1,302 @@
1
+ /**
2
+ * Before portable export: upgrade extant Layer 1 subscription buses to Layer 2 (DID)
3
+ * so relationships (including community ↔ thing) survive cross-engine move + webvh rotate.
4
+ */
5
+
6
+ import { PicoFramework } from "pico-framework";
7
+ import {
8
+ establishSubscriptionIdentity,
9
+ linkRemotePeer,
10
+ } from "./establishSubscription";
11
+ import type { IdentityStore } from "./store";
12
+ import type { PortableMoveDeps } from "./portableMove";
13
+
14
+ const SUBSCRIPTION_RID = "io.picolabs.subscription";
15
+
16
+ export interface PortableExportPrepareResult {
17
+ /** Subscription buses upgraded on picos inside the export subtree. */
18
+ upgradedOnSubtree: number;
19
+ /** Reciprocal buses upgraded on peers outside the subtree (same engine). */
20
+ upgradedOnPeers: number;
21
+ /** Buses skipped (already L2, no remote Tx, or remote did not resolve). */
22
+ skipped: number;
23
+ }
24
+
25
+ function busId(bus: Record<string, unknown>): string | undefined {
26
+ const id = bus["Id"];
27
+ return typeof id === "string" && id.length > 0 ? id : undefined;
28
+ }
29
+
30
+ function collectSubtreePicoIds(pf: PicoFramework, picoRef: string): string[] {
31
+ const pico = pf.getPico(picoRef);
32
+ const ids = [pico.id];
33
+ for (const childEci of pico.toReadOnly().children) {
34
+ const child = pf.lookupChannel(childEci).pico;
35
+ ids.push(...collectSubtreePicoIds(pf, child.id));
36
+ }
37
+ return ids;
38
+ }
39
+
40
+ /** Read did:webvh from the identity store — never pf.query (deadlocks during export KRL query). */
41
+ async function webvhDidForChannelEci(
42
+ store: IdentityStore,
43
+ pf: PicoFramework,
44
+ remoteEci: string
45
+ ): Promise<string | null> {
46
+ try {
47
+ const did = await store.getWebvhDid(pf.getPico(remoteEci).id);
48
+ return typeof did === "string" && did.length > 0 ? did : null;
49
+ } catch {
50
+ return null;
51
+ }
52
+ }
53
+
54
+ function mergeBusToLayer2(
55
+ bus: Record<string, unknown>,
56
+ remoteWebvhDid: string,
57
+ rxPeerDid: string
58
+ ): Record<string, unknown> {
59
+ return {
60
+ ...bus,
61
+ layer2: true,
62
+ Tx_did: remoteWebvhDid,
63
+ Rx_did: rxPeerDid,
64
+ Tx: "",
65
+ };
66
+ }
67
+
68
+ async function upgradeEstablishedList(
69
+ store: IdentityStore,
70
+ pf: PicoFramework,
71
+ picoId: string,
72
+ list: Record<string, unknown>[]
73
+ ): Promise<{
74
+ next: Record<string, unknown>[];
75
+ upgraded: number;
76
+ skipped: number;
77
+ reciprocals: Array<{ remotePicoId: string; localWebvhDid: string; subId: string }>;
78
+ }> {
79
+ const localDid = await store.getWebvhDid(picoId);
80
+ const reciprocals: Array<{
81
+ remotePicoId: string;
82
+ localWebvhDid: string;
83
+ subId: string;
84
+ }> = [];
85
+ let upgraded = 0;
86
+ let skipped = 0;
87
+ const next: Record<string, unknown>[] = [];
88
+
89
+ for (const raw of list) {
90
+ if (!raw || typeof raw !== "object") {
91
+ next.push(raw as Record<string, unknown>);
92
+ continue;
93
+ }
94
+ const bus = { ...(raw as Record<string, unknown>) };
95
+ if (bus["layer2"] === true) {
96
+ next.push(bus);
97
+ skipped += 1;
98
+ continue;
99
+ }
100
+
101
+ const subId = busId(bus);
102
+ const remoteEci =
103
+ typeof bus["Tx"] === "string" && bus["Tx"].length > 0
104
+ ? bus["Tx"]
105
+ : undefined;
106
+
107
+ if (!subId || !remoteEci) {
108
+ next.push(bus);
109
+ skipped += 1;
110
+ continue;
111
+ }
112
+
113
+ const remoteWebvhDid = await webvhDidForChannelEci(store, pf, remoteEci);
114
+ if (!remoteWebvhDid) {
115
+ next.push(bus);
116
+ skipped += 1;
117
+ continue;
118
+ }
119
+
120
+ const established = await establishSubscriptionIdentity(store, pf, picoId, {
121
+ subscriptionId: subId,
122
+ remoteWebvhDid,
123
+ remoteTxHost:
124
+ typeof bus["Tx_host"] === "string" ? bus["Tx_host"] : undefined,
125
+ rxEci: typeof bus["Rx"] === "string" ? bus["Rx"] : undefined,
126
+ channelName:
127
+ typeof bus["name"] === "string" ? bus["name"] : undefined,
128
+ channelType:
129
+ typeof bus["channel_type"] === "string"
130
+ ? bus["channel_type"]
131
+ : undefined,
132
+ });
133
+
134
+ next.push(mergeBusToLayer2(bus, remoteWebvhDid, established.peerDid));
135
+ upgraded += 1;
136
+
137
+ if (localDid) {
138
+ try {
139
+ const remotePico = pf.getPico(remoteEci);
140
+ reciprocals.push({
141
+ remotePicoId: remotePico.id,
142
+ localWebvhDid: localDid,
143
+ subId,
144
+ });
145
+ } catch {
146
+ // remote not on this engine
147
+ }
148
+ }
149
+ }
150
+
151
+ return { next, upgraded, skipped, reciprocals };
152
+ }
153
+
154
+ async function upgradeReciprocalBuses(
155
+ store: IdentityStore,
156
+ pf: PicoFramework,
157
+ remotePicoId: string,
158
+ localPicoId: string,
159
+ localWebvhDid: string
160
+ ): Promise<number> {
161
+ const remote = pf.loadedPicos().find((p) => p.id === remotePicoId);
162
+ if (!remote?.rulesets[SUBSCRIPTION_RID]) {
163
+ return 0;
164
+ }
165
+
166
+ const establishedRaw = await remote.getEnt(SUBSCRIPTION_RID, "established");
167
+ if (!Array.isArray(establishedRaw) || establishedRaw.length === 0) {
168
+ return 0;
169
+ }
170
+
171
+ let upgraded = 0;
172
+ const next: Record<string, unknown>[] = [];
173
+
174
+ for (const raw of establishedRaw) {
175
+ if (!raw || typeof raw !== "object") {
176
+ next.push(raw as Record<string, unknown>);
177
+ continue;
178
+ }
179
+ const bus = { ...(raw as Record<string, unknown>) };
180
+ if (bus["layer2"] === true) {
181
+ next.push(bus);
182
+ continue;
183
+ }
184
+
185
+ const subId = busId(bus);
186
+ const tx =
187
+ typeof bus["Tx"] === "string" && bus["Tx"].length > 0
188
+ ? bus["Tx"]
189
+ : undefined;
190
+
191
+ let pointsAtLocal = bus["picoID"] === localPicoId;
192
+ if (!pointsAtLocal && tx) {
193
+ try {
194
+ pointsAtLocal = pf.getPico(tx).id === localPicoId;
195
+ } catch {
196
+ pointsAtLocal = false;
197
+ }
198
+ }
199
+
200
+ if (!subId || !pointsAtLocal) {
201
+ next.push(bus);
202
+ continue;
203
+ }
204
+
205
+ const established = await establishSubscriptionIdentity(
206
+ store,
207
+ pf,
208
+ remotePicoId,
209
+ {
210
+ subscriptionId: subId,
211
+ remoteWebvhDid: localWebvhDid,
212
+ remoteTxHost:
213
+ typeof bus["Tx_host"] === "string" ? bus["Tx_host"] : undefined,
214
+ rxEci: typeof bus["Rx"] === "string" ? bus["Rx"] : undefined,
215
+ }
216
+ );
217
+
218
+ const thingSub = await store.getPeerSubscription(localPicoId, subId);
219
+ const remoteWebvh = await store.getWebvhDid(remotePicoId);
220
+ const txHost =
221
+ typeof bus["Tx_host"] === "string" ? bus["Tx_host"] : undefined;
222
+
223
+ if (thingSub?.peerDid) {
224
+ await linkRemotePeer(store, remotePicoId, subId, {
225
+ remotePeerDid: thingSub.peerDid,
226
+ remoteWebvhDid: localWebvhDid,
227
+ remoteTxHost: txHost,
228
+ });
229
+ await linkRemotePeer(store, localPicoId, subId, {
230
+ remotePeerDid: established.peerDid,
231
+ remoteWebvhDid: remoteWebvh ?? undefined,
232
+ remoteTxHost: txHost,
233
+ });
234
+ }
235
+
236
+ next.push(mergeBusToLayer2(bus, localWebvhDid, established.peerDid));
237
+ upgraded += 1;
238
+ }
239
+
240
+ if (upgraded > 0) {
241
+ await remote.putEnt(SUBSCRIPTION_RID, "established", next);
242
+ }
243
+ return upgraded;
244
+ }
245
+
246
+ /** Upgrade extant L1 established buses to L2 for every pico in the export subtree. */
247
+ export async function prepareSubtreeRelationshipsForPortableExport(
248
+ deps: Pick<PortableMoveDeps, "store" | "pf" | "identity">,
249
+ subtreeRootRef: string
250
+ ): Promise<PortableExportPrepareResult> {
251
+ const subtreeIds = new Set(collectSubtreePicoIds(deps.pf, subtreeRootRef));
252
+ let upgradedOnSubtree = 0;
253
+ let upgradedOnPeers = 0;
254
+ let skipped = 0;
255
+ const reciprocalSeen = new Set<string>();
256
+
257
+ for (const picoId of subtreeIds) {
258
+ const pico = deps.pf.loadedPicos().find((p) => p.id === picoId);
259
+ if (!pico?.rulesets[SUBSCRIPTION_RID]) {
260
+ continue;
261
+ }
262
+
263
+ const establishedRaw = await pico.getEnt(SUBSCRIPTION_RID, "established");
264
+ if (!Array.isArray(establishedRaw) || establishedRaw.length === 0) {
265
+ continue;
266
+ }
267
+
268
+ const list = establishedRaw.filter(
269
+ (b) => b && typeof b === "object"
270
+ ) as Record<string, unknown>[];
271
+
272
+ const {
273
+ next,
274
+ upgraded,
275
+ skipped: skip,
276
+ reciprocals,
277
+ } = await upgradeEstablishedList(deps.store, deps.pf, picoId, list);
278
+
279
+ skipped += skip;
280
+ if (upgraded > 0) {
281
+ await pico.putEnt(SUBSCRIPTION_RID, "established", next);
282
+ upgradedOnSubtree += upgraded;
283
+ }
284
+
285
+ for (const r of reciprocals) {
286
+ const key = `${r.remotePicoId}:${r.localWebvhDid}`;
287
+ if (reciprocalSeen.has(key)) {
288
+ continue;
289
+ }
290
+ reciprocalSeen.add(key);
291
+ upgradedOnPeers += await upgradeReciprocalBuses(
292
+ deps.store,
293
+ deps.pf,
294
+ r.remotePicoId,
295
+ picoId,
296
+ r.localWebvhDid
297
+ );
298
+ }
299
+ }
300
+
301
+ return { upgradedOnSubtree, upgradedOnPeers, skipped };
302
+ }
@@ -0,0 +1,193 @@
1
+ /**
2
+ * End-to-end portable move: export subtree + identity, import, relocate, notify peers.
3
+ */
4
+
5
+ import { Pico, PicoFramework } from "pico-framework";
6
+ import {
7
+ exportSubtree,
8
+ importIntoExistingChild,
9
+ subtreeRootBootstrapName,
10
+ type SubtreeImportOptions,
11
+ type SubtreeImportResult,
12
+ } from "pico-engine-core";
13
+ import { createImportChildViaWrangler } from "../subtreeWrangler";
14
+ import { wranglerSubtreeImportServices } from "../subtreeWrangler";
15
+ import type { RulesetRegistry } from "pico-engine-core";
16
+ import { IdentityStore } from "./store";
17
+ import type { IdentityService } from "./IdentityService";
18
+ import type {
19
+ RelocateWebvhOptions,
20
+ RelocateWebvhResult,
21
+ } from "./webvhRelocation";
22
+ import { refreshLocalPeersOfMovedRoot } from "./localPeerReconcile";
23
+ import { prepareSubtreeRelationshipsForPortableExport } from "./portableExportPrepare";
24
+ import { syncLayer2EstablishedFromIdentity } from "./subscriptionEntSync";
25
+
26
+ export interface PortableMoveDeps {
27
+ store: IdentityStore;
28
+ pf: PicoFramework;
29
+ rsRegistry: RulesetRegistry;
30
+ identity: IdentityService;
31
+ getBaseUrl: () => string;
32
+ resolveBundledRulesetUrl?: (url: string) => string;
33
+ reloadImportedSchedules?(picoIds: string[]): Promise<void>;
34
+ firePicoImported?(result: SubtreeImportResult): Promise<void>;
35
+ }
36
+
37
+ export interface PortableMoveExportResult {
38
+ blob: string;
39
+ }
40
+
41
+ export type PortableImportRelocation =
42
+ | (RelocateWebvhResult & { peersNotified: number })
43
+ | { skipped: true; peersNotified: 0 };
44
+
45
+ export interface PortableMoveImportResult extends SubtreeImportResult {
46
+ relocation: PortableImportRelocation;
47
+ }
48
+
49
+ function resolveImportBootstrapName(
50
+ blob: string,
51
+ secret: string,
52
+ displayNameOverride?: string
53
+ ): string {
54
+ const override = displayNameOverride?.trim();
55
+ if (override) {
56
+ return override;
57
+ }
58
+ try {
59
+ const fromBlob = subtreeRootBootstrapName(blob, secret);
60
+ if (fromBlob !== "imported") {
61
+ return fromBlob;
62
+ }
63
+ } catch {
64
+ // invalid blob handled later in importIntoExistingChild
65
+ }
66
+ return "imported";
67
+ }
68
+
69
+ function subtreeServices(deps: PortableMoveDeps) {
70
+ return {
71
+ db: deps.pf.db,
72
+ rsRegistry: deps.rsRegistry,
73
+ portableHooks: deps.identity.subtreePortableHooks(),
74
+ resolveBundledRulesetUrl: deps.resolveBundledRulesetUrl,
75
+ ...wranglerSubtreeImportServices(deps.rsRegistry),
76
+ };
77
+ }
78
+
79
+ /** Export a subtree including identity snapshots for each pico. */
80
+ export async function exportPortableSubtree(
81
+ deps: PortableMoveDeps,
82
+ picoId: string,
83
+ secret: string,
84
+ options?: { recurse?: boolean; skipRelationshipUpgrade?: boolean }
85
+ ): Promise<string> {
86
+ if (options?.skipRelationshipUpgrade !== true) {
87
+ await prepareSubtreeRelationshipsForPortableExport(deps, picoId);
88
+ }
89
+ return exportSubtree(
90
+ subtreeServices(deps),
91
+ deps.pf,
92
+ picoId,
93
+ secret,
94
+ options
95
+ );
96
+ }
97
+
98
+ /** Relocate webvh + ingress for every imported pico; notify peers from the moved root. */
99
+ export async function finalizePortableImport(
100
+ deps: PortableMoveDeps,
101
+ importResult: SubtreeImportResult,
102
+ relocateOptions: RelocateWebvhOptions = { renewIngress: true }
103
+ ): Promise<PortableMoveImportResult["relocation"]> {
104
+ const importedPicoIds = Object.values(importResult.picoIdMap);
105
+ for (const picoId of importedPicoIds) {
106
+ if (picoId === importResult.newRootPicoId) {
107
+ continue;
108
+ }
109
+ if (await deps.store.getWebvhDid(picoId)) {
110
+ await deps.identity.relocateWebvhAfterMove(picoId, relocateOptions);
111
+ }
112
+ }
113
+ const rootDid = await deps.store.getWebvhDid(importResult.newRootPicoId);
114
+ if (!rootDid) {
115
+ return { skipped: true, peersNotified: 0 };
116
+ }
117
+ const relocation = await deps.identity.completePortableMove(
118
+ importResult.newRootPicoId,
119
+ relocateOptions
120
+ );
121
+ await refreshLocalPeersOfMovedRoot(
122
+ deps.pf,
123
+ importResult,
124
+ relocation,
125
+ deps.getBaseUrl()
126
+ );
127
+ return relocation;
128
+ }
129
+
130
+ async function afterPortableHydrate(
131
+ deps: PortableMoveDeps,
132
+ result: SubtreeImportResult
133
+ ): Promise<void> {
134
+ if (deps.reloadImportedSchedules) {
135
+ await deps.reloadImportedSchedules(Object.values(result.picoIdMap));
136
+ }
137
+ for (const picoId of Object.values(result.picoIdMap)) {
138
+ await syncLayer2EstablishedFromIdentity(deps.store, deps.pf, picoId);
139
+ }
140
+ if (deps.firePicoImported) {
141
+ await deps.firePicoImported(result);
142
+ }
143
+ }
144
+
145
+ /** Import a portable subtree under parent and finalize relocation + peer notification. */
146
+ export async function importPortableSubtree(
147
+ deps: PortableMoveDeps,
148
+ parent: Pico,
149
+ blob: string,
150
+ secret: string,
151
+ relocateOptions?: RelocateWebvhOptions,
152
+ importOptions?: SubtreeImportOptions
153
+ ): Promise<PortableMoveImportResult> {
154
+ const services = subtreeServices(deps);
155
+ const createOpts = importOptions?.parentChannelEci
156
+ ? { channelEci: importOptions.parentChannelEci }
157
+ : undefined;
158
+ const bootstrapName = resolveImportBootstrapName(
159
+ blob,
160
+ secret,
161
+ importOptions?.bootstrapDisplayName
162
+ );
163
+ const { familyEci } = await createImportChildViaWrangler(
164
+ deps.pf,
165
+ parent,
166
+ bootstrapName,
167
+ deps.rsRegistry,
168
+ createOpts
169
+ );
170
+ const importResult = await importIntoExistingChild(
171
+ services,
172
+ deps.pf,
173
+ parent,
174
+ familyEci,
175
+ blob,
176
+ secret,
177
+ {
178
+ ...importOptions,
179
+ async afterImport(result, payload) {
180
+ if (importOptions?.afterImport) {
181
+ await importOptions.afterImport(result, payload);
182
+ }
183
+ await afterPortableHydrate(deps, result);
184
+ },
185
+ }
186
+ );
187
+ const relocation = await finalizePortableImport(
188
+ deps,
189
+ importResult,
190
+ relocateOptions
191
+ );
192
+ return { ...importResult, relocation };
193
+ }
@@ -310,16 +310,16 @@ export async function handleSkyIntroResponseAtIngress(
310
310
  Id: subscriptionId,
311
311
  });
312
312
 
313
- await deps.pf.eventWait(
314
- {
315
- eci,
316
- domain: "wrangler",
317
- name: "sky_intro_response",
318
- data: { attrs },
319
- time: 0,
320
- },
321
- undefined
322
- );
313
+ // Queue without waiting: the Tx pico may still be inside the outbound
314
+ // subscription transaction that triggered sendSkyIntro (same-engine local
315
+ // dispatch or cross-engine HTTP). eventWait here deadlocks that queue.
316
+ await deps.pf.event({
317
+ eci,
318
+ domain: "wrangler",
319
+ name: "sky_intro_response",
320
+ data: { attrs },
321
+ time: 0,
322
+ });
323
323
 
324
- return { status: "intro_response_delivered", subscriptionId };
324
+ return { status: "intro_response_queued", subscriptionId };
325
325
  }
@@ -7,6 +7,7 @@ export const SKY_INTRO_RESPONSE = `${SKY_NS}/intro-response`;
7
7
  export const SKY_EVENT = `${SKY_NS}/event`;
8
8
  export const SKY_QUERY = `${SKY_NS}/query`;
9
9
  export const SKY_QUERY_RESPONSE = `${SKY_NS}/query-response`;
10
+ export const SKY_ROTATE = `${SKY_NS}/rotate`;
10
11
 
11
12
  export interface SkyEventBody {
12
13
  sky_version: string;
@@ -45,6 +46,14 @@ export interface SkyIntroBody {
45
46
  subscription_id?: string;
46
47
  }
47
48
 
49
+ export interface SkyRotateBody {
50
+ sky_version: string;
51
+ prior_webvh_did: string;
52
+ new_webvh_did: string;
53
+ new_tx_host?: string;
54
+ new_didcomm_endpoint?: string;
55
+ }
56
+
48
57
  export interface SkyIntroResponseBody {
49
58
  sky_version: string;
50
59
  status: "accepted" | "rejected";
@@ -149,6 +158,43 @@ export function skyIntroResponseToWranglerAttrs(
149
158
  };
150
159
  }
151
160
 
161
+ export function parseSkyRotateBody(body: unknown): SkyRotateBody {
162
+ if (!body || typeof body !== "object") {
163
+ throw new Error("Invalid SKY rotate body");
164
+ }
165
+ const b = body as Record<string, unknown>;
166
+ if (
167
+ typeof b.prior_webvh_did !== "string" ||
168
+ typeof b.new_webvh_did !== "string"
169
+ ) {
170
+ throw new Error("SKY rotate body missing prior_webvh_did or new_webvh_did");
171
+ }
172
+ return {
173
+ sky_version: String(b.sky_version || "1.0"),
174
+ prior_webvh_did: b.prior_webvh_did,
175
+ new_webvh_did: b.new_webvh_did,
176
+ new_tx_host:
177
+ typeof b.new_tx_host === "string" ? b.new_tx_host : undefined,
178
+ new_didcomm_endpoint:
179
+ typeof b.new_didcomm_endpoint === "string"
180
+ ? b.new_didcomm_endpoint
181
+ : undefined,
182
+ };
183
+ }
184
+
185
+ export function skyRotateToWranglerAttrs(
186
+ rotate: SkyRotateBody,
187
+ extras: Record<string, unknown> = {}
188
+ ): Record<string, unknown> {
189
+ return {
190
+ prior_webvh_did: rotate.prior_webvh_did,
191
+ new_webvh_did: rotate.new_webvh_did,
192
+ new_tx_host: rotate.new_tx_host,
193
+ new_didcomm_endpoint: rotate.new_didcomm_endpoint,
194
+ ...extras,
195
+ };
196
+ }
197
+
152
198
  export function parseSkyEventBody(body: unknown): SkyEventBody {
153
199
  if (!body || typeof body !== "object") {
154
200
  throw new Error("Invalid SKY event body");