@kubun/plugin-p2p 0.15.1 → 0.16.0

package/lib/groups/group-protocols.d.ts

@@ -508,9 +508,404 @@ export declare const peerProtocol: {
         };
     };
 };
+/**
+ * Workflow plane: remote observation of a device's durable workflow instances.
+ * Mounted only when this device runs the workflow plugin (see the manager's
+ * conditional composition) — absent it, no `workflow` topic exists and a gather
+ * on this lane routes to nothing.
+ *
+ * ATTRIBUTION IS THE LANE'S, NOT THE BODY'S, as on the peer plane: the reply is a
+ * bare `InstanceStatus[]` and the gather envelope supplies the responder's
+ * authenticated `senderDID`, so the body names no device.
+ */
+export declare const workflowProtocol: {
+    readonly 'workflow/discover': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask co-members which of their workflow instances are remotely observable. Gathered: each device replies with only its own remote.observe instances.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly instanceID: {
+                        readonly type: "string";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly queue: {
+                        readonly type: "string";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                    };
+                    readonly attempts: {
+                        readonly type: "number";
+                    };
+                    readonly lastError: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly createdAt: {
+                        readonly type: "number";
+                    };
+                    readonly updatedAt: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly 'workflow/list': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask one peer (directed) for its remotely-observable workflow instances. The peer replies with only its own remote.observe instances.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {};
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly instanceID: {
+                        readonly type: "string";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly queue: {
+                        readonly type: "string";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                    };
+                    readonly attempts: {
+                        readonly type: "number";
+                    };
+                    readonly lastError: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly createdAt: {
+                        readonly type: "number";
+                    };
+                    readonly updatedAt: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly 'workflow/status': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask one peer (directed) for one instance status by id. A non-observable instance is refused identically to an unknown one, so the reply never reveals that a hidden instance exists.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly instanceID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["instanceID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly instanceID: {
+                    readonly type: "string";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly queue: {
+                    readonly type: "string";
+                };
+                readonly status: {
+                    readonly type: "string";
+                };
+                readonly attempts: {
+                    readonly type: "number";
+                };
+                readonly lastError: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly createdAt: {
+                    readonly type: "number";
+                };
+                readonly updatedAt: {
+                    readonly type: "number";
+                };
+            };
+            readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'workflow/enqueue': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask one peer (directed) to enqueue a named workflow. Directed addressing means exactly one device runs it — no double-execution. A workflow that did not opt into remote command is refused with `not_commandable`; success returns the new instance status.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly params: {};
+                readonly opts: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly queue: {
+                            readonly type: "string";
+                        };
+                        readonly priority: {
+                            readonly type: "number";
+                        };
+                        readonly idempotencyKey: {
+                            readonly type: "string";
+                        };
+                        readonly singletonKey: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly required: readonly ["name"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: true;
+                    };
+                    readonly status: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly instanceID: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly queue: {
+                                readonly type: "string";
+                            };
+                            readonly status: {
+                                readonly type: "string";
+                            };
+                            readonly attempts: {
+                                readonly type: "number";
+                            };
+                            readonly lastError: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly createdAt: {
+                                readonly type: "number";
+                            };
+                            readonly updatedAt: {
+                                readonly type: "number";
+                            };
+                        };
+                        readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly required: readonly ["ok", "status"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: false;
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not_commandable", "not_found", "not_failed", "no_next_action", "singleton"];
+                    };
+                };
+                readonly required: readonly ["ok", "reason"];
+                readonly additionalProperties: false;
+            }];
+        };
+    };
+    readonly 'workflow/cancel': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask one peer (directed) to cancel one instance by id. A non-commandable instance is refused identically to an unknown one (`not_found`), so the reply never reveals that a hidden instance exists.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly instanceID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["instanceID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: true;
+                    };
+                    readonly status: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly instanceID: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly queue: {
+                                readonly type: "string";
+                            };
+                            readonly status: {
+                                readonly type: "string";
+                            };
+                            readonly attempts: {
+                                readonly type: "number";
+                            };
+                            readonly lastError: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly createdAt: {
+                                readonly type: "number";
+                            };
+                            readonly updatedAt: {
+                                readonly type: "number";
+                            };
+                        };
+                        readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly required: readonly ["ok", "status"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: false;
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not_commandable", "not_found", "not_failed", "no_next_action", "singleton"];
+                    };
+                };
+                readonly required: readonly ["ok", "reason"];
+                readonly additionalProperties: false;
+            }];
+        };
+    };
+    readonly 'workflow/retry': {
+        readonly type: "request";
+        readonly retain: "ephemeral";
+        readonly description: "Ask one peer (directed) to re-arm one failed instance by id. A non-commandable instance is refused identically to an unknown one (`not_found`); the engine's own retry refusals (`not_failed`/`no_next_action`/`singleton`) map through verbatim.";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly instanceID: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["instanceID"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly anyOf: [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: true;
+                    };
+                    readonly status: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly instanceID: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly queue: {
+                                readonly type: "string";
+                            };
+                            readonly status: {
+                                readonly type: "string";
+                            };
+                            readonly attempts: {
+                                readonly type: "number";
+                            };
+                            readonly lastError: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly createdAt: {
+                                readonly type: "number";
+                            };
+                            readonly updatedAt: {
+                                readonly type: "number";
+                            };
+                        };
+                        readonly required: readonly ["instanceID", "name", "queue", "status", "attempts", "lastError", "createdAt", "updatedAt"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly required: readonly ["ok", "status"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                        readonly const: false;
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not_commandable", "not_found", "not_failed", "no_next_action", "singleton"];
+                    };
+                };
+                readonly required: readonly ["ok", "reason"];
+                readonly additionalProperties: false;
+            }];
+        };
+    };
+};
 export type ControlProtocol = typeof controlProtocol;
 export type SyncProtocol = typeof syncProtocol;
 export type PeerProtocol = typeof peerProtocol;
+export type WorkflowProtocol = typeof workflowProtocol;
+/**
+ * A directed command's wire result: `{ ok:true, status }` on success or
+ * `{ ok:false, reason }` on a business refusal. Derived from the enqueue result
+ * schema — the three commands share one shape.
+ */
+export type WorkflowCommandResult = FromSchema<(typeof workflowProtocol)['workflow/enqueue']['result']>;
+/** The machine reason a refused command carries. */
+export type WorkflowCommandRefusalReason = Extract<WorkflowCommandResult, {
+    ok: false;
+}>['reason'];
 export type LedgerCatchupResult = FromSchema<(typeof controlProtocol)['control/ledgerCatchup']['result']>;
 export type DelegationShareData = FromSchema<(typeof controlProtocol)['control/delegationShare']['data']>;
 export type DelegationRevokeData = FromSchema<(typeof controlProtocol)['control/delegationRevoke']['data']>;
@@ -1026,3 +1421,15 @@ export declare const groupProtocols: {
     };
 };
 export type GroupProtocols = typeof groupProtocols;
+/**
+ * The group protocols with the `workflow` lane conditionally mounted. A FRESH
+ * object each call — the shared static {@link groupProtocols} is never mutated.
+ * When `hasWorkflow` is false the base map is returned unchanged, so no
+ * `workflow` key exists and a gather on that lane routes to nothing.
+ *
+ * The workflow lane is an extra runtime key served by `createGroupPeer`
+ * (`Object.entries(protocols)`), but callers stay typed at the base shape: the
+ * manager never statically routes `workflow`, and the peer it holds keeps its
+ * base type. The paired handler is composed by `composeGroupHandlers`.
+ */
+export declare function composeGroupProtocols(hasWorkflow: boolean): GroupProtocols;