@kubun/plugin-p2p 0.15.0 → 0.16.0

package/lib/groups/group-peer-manager.d.ts

@@ -1,9 +1,10 @@
 import type { ProcedureHandlers } from '@enkaku/server';
-import type { OwnIdentity } from '@kokuin/token';
+import { type DIDCache, type OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { WorkflowDiscoverOptions, WorkflowDiscoverReply } from '@kubun/plugin-p2p-api';
 import type { ServiceConfig } from '@kubun/plugin-service-api';
 import type { GraphStoreAPI } from '@kubun/store-graph';
 import { type GroupPeer, type LaneResult, type PendingCommit } from '@kumiai/rpc';
@@ -20,6 +21,7 @@ import { type SettleLostControlRequestDeps } from './commit-adoption.js';
 import { type ControllerResolverFor } from './credential-wrapping-deps.js';
 import type { P2PEventEmitter } from './events.js';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
+import { type WorkflowCommandAPI } from './group-handlers.js';
 import { type GroupProtocols } from './group-protocols.js';
 import { type PeerPresence } from './peer-presence.js';
 /**
@@ -64,6 +66,22 @@ export type GroupPeerManagerParams = {
     graph: GraphInternals;
     /** Device-wide monotonic clock shared with the engine and MLS receive path. */
     hlc: HLC;
+    /**
+     * The engine's identity gate, forwarded to the presence coordinator so a
+     * self-started announce awaits verification before it mints under `hlc`.
+     * Absent for a by-hand test manager, whose ungated clock needs no wait.
+     */
+    ready?: () => Promise<void>;
+    /**
+     * Resolve the device's workflow API, if the workflow plugin is loaded. When it
+     * resolves non-null a `workflow` namespace is mounted on each hub peer so
+     * co-members can gather this device's remotely-observable instances; null
+     * leaves the peer's protocol map unchanged. Async because the engine resolves
+     * plugin APIs only after every factory has returned — a peer is created on
+     * `groupJoined`, well after that, so it is normally already resolved. Absent
+     * for a by-hand test manager, which mounts no workflow lane.
+     */
+    getWorkflowAPI?: () => Promise<WorkflowCommandAPI | undefined>;
     /**
      * The engine's future-drift bound, forwarded to the apply path. Optional: a
      * suite that builds a manager by hand falls back to the same default the
@@ -132,20 +150,17 @@ export type GroupPeerManagerParams = {
     serviceServe?: ServeService;
     /** Which services to serve on an inbound service-lane session. */
     services?: Record<string, ServiceConfig>;
+    /**
+     * Shared, plugin-lifetime DID cache forwarded to the sync- and service-tunnel
+     * listeners, which seed it from each group's roster and hand it to every
+     * spawned session's Server (see {@link TunnelListenersParams.cache}).
+     */
+    cache?: DIDCache;
     /** @see TunnelListenersParams.idleTimeoutMs */
     tunnelIdleTimeoutMs?: number;
 };
-/**
- * Coordinates the per-(group, hub) `GroupPeer`s for one device — full multi-hub.
- *
- * The manager owns one reconnecting `HubLike` per hub URL (created lazily on
- * first use, shared across every group bound to that hub via the multi-subscriber
- * adapter) and one `GroupPeer` per (group, hub) pair. A peer exists iff the group
- * is joined AND bound to that hub. Lifecycle mirrors the old `HubRelayManager`,
- * but per (group, hub) instead of single-hub: the wiring phase drives `addGroup`
- * / `removeGroup` / `addBinding` / `removeBinding` from the emitter and holds the
- * unsubscribes. The manager does not subscribe to the emitter itself.
- */
+/** The directed (non-gather) `workflow/*` procedures {@link GroupPeerManager.requestWorkflow} carries. */
+export type WorkflowRequestMethod = 'workflow/list' | 'workflow/status' | 'workflow/enqueue' | 'workflow/cancel' | 'workflow/retry';
 export type GroupPeerManager = {
     /** Bring up peers for each already-bound hub of each joined group. */
     start: (groupIDs: Array<string>) => Promise<void>;
@@ -168,6 +183,13 @@ export type GroupPeerManager = {
     reconcileTunnelListeners: (groupID: string) => Promise<void>;
     /** Fan a broadcast message out across every hub-peer of a group. */
     broadcast: (groupID: string, message: GroupBroadcastMessage) => Promise<void>;
+    /**
+     * Ask every hub-peer of the group to re-drive a subscription its hub refused — the recovery for a
+     * device whose group topics were subscribed on join, before its app-level authorization landed,
+     * and so were refused `AuthorizationDeniedError` and latched. Synchronous and idempotent (a no-op
+     * on a peer holding nothing refused); the app calls it once it knows the device is authorized.
+     */
+    reauthorize: (groupID: string) => void;
     /**
      * This device's presence on the peer lane: what it advertises, and who it asks.
      * The manager owns it because every internal trigger fires from here — a hub
@@ -175,6 +197,24 @@ export type GroupPeerManager = {
      * the group's live peers.
      */
     presence: PeerPresence;
+    /**
+     * Fan `workflow/discover` out across every hub-peer of the group and return one
+     * entry per DISTINCT responder, deduped by the authenticated `senderDID` the
+     * gather envelope carried (self dropped), each `{ senderDID, instances }`. The
+     * multi-hub transport behind the caller-facing control-plane API — a member
+     * reachable through two hubs answers on both and is counted once.
+     */
+    discoverWorkflows: (groupID: string, options?: WorkflowDiscoverOptions) => Promise<Array<WorkflowDiscoverReply>>;
+    /**
+     * Directed `workflow/*` request to one co-member over the group's hub:
+     * `.to(targetDID).request(method, { param })` on a bound hub-peer, retried
+     * across the remaining bindings only when a hub THROWS (an infra fault before
+     * anything is delivered) — never on a returned business refusal, which is the
+     * answer. Backs list/status/enqueue/cancel/retry; returns the raw wire result
+     * for the typed pluginAPI method to shape. Throws when the group has no live
+     * hub-peer, or rethrows the last hub's error.
+     */
+    requestWorkflow: (groupID: string, targetDID: string, method: WorkflowRequestMethod, param?: Record<string, unknown>) => Promise<unknown>;
     /**
      * The peer for the group's canonical commit hub — the single hub a group
      * commits through. Resolves the designated commit hub; falls back to the live

package/lib/groups/group-peer-manager.js

@@ -1,3 +1,4 @@
+import { normalizeDID } from '@kokuin/token';
 import { CREDENTIAL_STORE, getCredentialStore } from '@kubun/store-credential';
 import { getDelegationStore } from '@kubun/store-delegation';
 import { getP2PStore } from '@kubun/store-p2p';
@@ -19,9 +20,9 @@ import { createCommitJournal } from './commit-journal.js';
 import { settleControlRequest } from './control-request.js';
 import { createCredentialWrappingDeps } from './credential-wrapping-deps.js';
 import { createGroupCrypto } from './group-crypto.js';
-import { buildGroupHandlers } from './group-handlers.js';
+import { buildGroupHandlers, composeGroupHandlers } from './group-handlers.js';
 import { createGroupMLS } from './group-mls.js';
-import { groupProtocols } from './group-protocols.js';
+import { composeGroupProtocols } from './group-protocols.js';
 import { ledgerEntryDigest } from './ledger.js';
 import { bootstrapGroupLedger } from './ledger-adopt.js';
 import { createPeerPresence } from './peer-presence.js';
@@ -37,20 +38,26 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
     switch(message.type){
         case 'delegation:share':
             await peer.protocol('control').dispatch('control/delegationShare', {
-                token: message.token,
-                hlc: message.hlc
+                data: {
+                    token: message.token,
+                    hlc: message.hlc
+                }
             });
             return;
         case 'delegation:revoke':
             await peer.protocol('control').dispatch('control/delegationRevoke', {
-                token: message.token,
-                hlc: message.hlc
+                data: {
+                    token: message.token,
+                    hlc: message.hlc
+                }
             });
             return;
         case 'group:leaveRequest':
             await peer.protocol('control').dispatch('control/groupLeaveRequest', {
-                memberDID: message.memberDID,
-                hlc: message.hlc
+                data: {
+                    memberDID: message.memberDID,
+                    hlc: message.hlc
+                }
             });
             return;
         case 'access-default:set':
@@ -58,26 +65,32 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
             // just its author, so a payload that drops or renames one produces a frame
             // the receiver verifies and correctly rejects.
             await peer.protocol('control').dispatch('control/accessDefaultSet', {
-                modelID: message.modelID,
-                permissionType: message.permissionType,
-                rule: message.rule,
-                ownerDID: message.ownerDID,
-                hlc: message.hlc,
-                auth: message.auth
+                data: {
+                    modelID: message.modelID,
+                    permissionType: message.permissionType,
+                    rule: message.rule,
+                    ownerDID: message.ownerDID,
+                    hlc: message.hlc,
+                    auth: message.auth
+                }
             });
             return;
         case 'access-default:remove':
             await peer.protocol('control').dispatch('control/accessDefaultRemove', {
-                modelID: message.modelID,
-                permissionTypes: message.permissionTypes,
-                ownerDID: message.ownerDID,
-                hlc: message.hlc,
-                auth: message.auth
+                data: {
+                    modelID: message.modelID,
+                    permissionTypes: message.permissionTypes,
+                    ownerDID: message.ownerDID,
+                    hlc: message.hlc,
+                    auth: message.auth
+                }
             });
             return;
         case 'mutation:apply':
             await peer.protocol('sync').dispatch('sync/mutationApply', {
-                entries: message.entries
+                data: {
+                    entries: message.entries
+                }
             });
             return;
         case 'peer:announce':
@@ -85,10 +98,12 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
             // lane resolved the sender to; putting it on the wire would create the
             // self-asserted DID field the whole design exists to avoid.
             await peer.protocol('peer').dispatch('peer/announce', {
-                label: message.label,
-                availability: message.availability,
-                capabilities: message.capabilities,
-                hlc: message.hlc
+                data: {
+                    label: message.label,
+                    availability: message.availability,
+                    capabilities: message.capabilities,
+                    hlc: message.hlc
+                }
             });
             return;
         case 'catalog:create':
@@ -104,23 +119,27 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
             // payload that dropped or rewrote one produces a frame the receiver
             // verifies and correctly rejects.
             await peer.protocol('control').dispatch('control/credentialKeyGrant', {
-                keyID: message.keyID,
-                keyVersion: message.keyVersion,
-                suite: message.suite,
-                ownerDID: message.ownerDID,
-                keyOp: message.keyOp,
-                keyBranches: message.keyBranches,
-                wrapping: message.wrapping,
-                entries: message.entries,
-                auth: message.auth
+                data: {
+                    keyID: message.keyID,
+                    keyVersion: message.keyVersion,
+                    suite: message.suite,
+                    ownerDID: message.ownerDID,
+                    keyOp: message.keyOp,
+                    keyBranches: message.keyBranches,
+                    wrapping: message.wrapping,
+                    entries: message.entries,
+                    auth: message.auth
+                }
             });
             return;
         case 'credential:key-manifest':
             // Both fields ride verbatim -- the token digests its own fields, so
             // reshaping would break signature verification.
             await peer.protocol('control').dispatch('control/credentialKeyManifest', {
-                manifest: message.manifest,
-                delegationTokens: message.delegationTokens
+                data: {
+                    manifest: message.manifest,
+                    delegationTokens: message.delegationTokens
+                }
             });
             return;
         default:
@@ -137,15 +156,14 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
  * True while a rotation has torn the per-epoch protocol runtimes down and not yet
  * rebuilt them.
  *
- * `createGroupPeer.rebuildEpoch` clears its runtime map synchronously and repopulates
- * it after awaiting every teardown, and `dispatch` takes no mutex — upstream says so
- * where it re-reads the anchor around a seal. So a broadcast that arrives inside that
- * window reaches `surfaceFor` with an empty map and gets `Unknown protocol: <name>`,
- * which is a transient rotation artefact and not a routing mistake. It is matched on
- * the message because the throw is a bare `Error`.
+ * `createGroupPeer.rebuildEpoch` clears its runtime map synchronously and
+ * repopulates it after awaiting every teardown, and `dispatch` takes no mutex. So
+ * a broadcast arriving inside that window reaches `surfaceFor` with an empty map
+ * and gets `Unknown protocol: <name>` — a transient rotation artefact, not a
+ * routing mistake. Matched on the message because the throw is a bare `Error`.
  *
- * Announce-on-epoch-change is exactly the trigger that publishes at a rotation, so
- * this window is on its normal path rather than at its edge.
+ * Announce-on-epoch-change publishes exactly at a rotation, so this window is on
+ * its normal path rather than at its edge.
  */ function isEpochRebuilding(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.startsWith('Unknown protocol: ');
@@ -580,7 +598,7 @@ export function createGroupPeerManager(params) {
     // (createGroupPeer restores the anchored MLS handle + opens the receive drain
     // in its constructor), so this must only run once the group's MLS state is
     // seeded (i.e. after `groupJoined`).
-    const instantiatePeer = ({ groupID, hub, processParams, initialEpoch })=>createGroupPeer({
+    const instantiatePeer = ({ groupID, hub, processParams, initialEpoch, workflowAPI })=>createGroupPeer({
             hub,
             crypto: createGroupCrypto({
                 registry: params.registry,
@@ -626,17 +644,17 @@ export function createGroupPeerManager(params) {
                     } : {}
                 }),
             localDID: params.localDID,
-            protocols: groupProtocols,
-            handlers: buildGroupHandlers(processParams, groupID),
+            // The workflow lane is mounted only when this device runs the workflow
+            // plugin — composed into FRESH maps, never mutating the shared statics.
+            protocols: composeGroupProtocols(workflowAPI != null),
+            handlers: composeGroupHandlers(buildGroupHandlers(processParams, groupID), workflowAPI),
             // App frames published while this device was away aged out of the hub's
-            // retention before it came back for them. The frames themselves are gone
-            // for good — nothing here replays them.
+            // retention before it came back — gone for good, nothing here replays them.
             //
-            // TRIGGER — a gap below the retention floor. It is not an error: what the
-            // gap means is "someone may have said something I will never read", and the
-            // repair for the peer lane is to re-announce and re-ask rather than to
-            // reconstruct the lost frames. An announcement is idempotent state, so a
-            // fresh one supersedes every lost one.
+            // TRIGGER — a gap below the retention floor. Not an error: it means "someone
+            // may have said something I will never read", and the peer lane's repair is
+            // to re-announce and re-ask, not reconstruct the lost frames. An
+            // announcement is idempotent, so a fresh one supersedes every lost one.
             onAppWindowPruned: (event)=>{
                 logger?.warn('app frames aged out below the hub retention floor', {
                     groupID: event.groupID,
@@ -661,7 +679,14 @@ export function createGroupPeerManager(params) {
         if (peers.has(key)) {
             return;
         }
-        const processParams = await buildProcessParams();
+        // Resolved in parallel with the store params: the engine memoizes the API,
+        // and `createPeer` runs on `groupJoined` — well after the engine's plugin
+        // gate closes — so this resolves without blocking. The re-checks below cover
+        // this suspension point exactly as they cover `buildProcessParams`.
+        const [processParams, workflowAPI] = await Promise.all([
+            buildProcessParams(),
+            params.getWorkflowAPI?.() ?? Promise.resolve(undefined)
+        ]);
         // Re-check after the await: a concurrent call may have installed this peer,
         // or `removeGroup` may have left the group, while the store resolved. The
         // emitter handlers (groupJoined/groupLeft/hubBound/hubUnbound) are not
@@ -680,7 +705,8 @@ export function createGroupPeerManager(params) {
             groupID,
             hub: getHubLike(hubURL),
             processParams,
-            initialEpoch
+            initialEpoch,
+            workflowAPI
         });
         peers.set(key, peer);
         let groupSet = bindings.get(groupID);
@@ -836,6 +862,9 @@ export function createGroupPeerManager(params) {
         stores: params.stores,
         localDID: params.localDID,
         hlc: params.hlc,
+        ...params.ready != null ? {
+            ready: params.ready
+        } : {},
         // Declaring a profile is what puts this device in co-members' projections,
         // so it is also what makes it dialable — the listeners come up here rather
         // than waiting for the next epoch.
@@ -880,7 +909,10 @@ export function createGroupPeerManager(params) {
                     return [];
                 }
                 try {
-                    return await throughRotation(()=>peer.protocol('peer').gather('peer/query', param, gatherOptions), 'gather peer/query', logger);
+                    return await throughRotation(()=>peer.protocol('peer').gather('peer/query', {
+                            param,
+                            ...gatherOptions
+                        }), 'gather peer/query', logger);
                 } catch (error) {
                     logger?.warn('peer query gather failed on a hub', {
                         groupID,
@@ -913,6 +945,9 @@ export function createGroupPeerManager(params) {
         localDID: params.localDID,
         runtime: tunnelRuntime,
         syncHandlers: params.syncHandlers,
+        ...params.cache != null ? {
+            cache: params.cache
+        } : {},
         tunnelHub: (groupID)=>{
             const hubURL = bindings.get(groupID)?.values().next().value;
             return hubURL == null ? undefined : getHubLike(hubURL);
@@ -932,6 +967,9 @@ export function createGroupPeerManager(params) {
         runtime: tunnelRuntime,
         serve: params.serviceServe,
         services: params.services,
+        ...params.cache != null ? {
+            cache: params.cache
+        } : {},
         tunnelHub: (groupID)=>{
             const hubURL = bindings.get(groupID)?.values().next().value;
             return hubURL == null ? undefined : getHubLike(hubURL);
@@ -1055,7 +1093,9 @@ export function createGroupPeerManager(params) {
             if (commitPeer == null) {
                 return 0;
             }
-            const replies = await commitPeer.protocol('control').gather('control/policyCatchup', {});
+            const replies = await commitPeer.protocol('control').gather('control/policyCatchup', {
+                param: {}
+            });
             // Every reply is applied, unlike the ledger's: a member restates only its
             // own rules, so two replies are two owners' policies rather than two
             // accounts of one thing. Nothing here chooses between them — each token is
@@ -1114,6 +1154,103 @@ export function createGroupPeerManager(params) {
         },
         addGroup,
         presence,
+        async discoverWorkflows (groupID, options) {
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null || groupSet.size === 0) {
+                return [];
+            }
+            // Bound the fan-out like `peer/query`: absent options, the gather runs its
+            // default window; a caller passing a member-count `quorum` returns as soon
+            // as everyone answers rather than waiting it out.
+            const gatherOptions = {
+                ...options?.timeoutMs != null ? {
+                    timeoutMs: options.timeoutMs
+                } : {},
+                ...options?.quorum != null ? {
+                    quorum: options.quorum
+                } : {}
+            };
+            // Fan out over every hub-peer concurrently, exactly as `presence.query`
+            // does — a dark hub burns only its own window, not the next one's.
+            const gathered = await Promise.all(Array.from(groupSet, async (hubURL)=>{
+                const peer = peers.get(peerKey(groupID, hubURL));
+                if (peer == null) {
+                    return [];
+                }
+                try {
+                    return await throughRotation(()=>peer.protocol('workflow').gather('workflow/discover', {
+                            param: {},
+                            ...gatherOptions
+                        }), 'gather workflow/discover', logger);
+                } catch (error) {
+                    logger?.warn('workflow discover gather failed on a hub', {
+                        groupID,
+                        hubURL,
+                        error
+                    });
+                    return [];
+                }
+            }));
+            // Attributed by the authenticated envelope, deduped by DID, self dropped —
+            // the same rule `peer-presence` applies to a `peer/query` reply. A member
+            // reachable via two hubs answers on both; the first wins, the rest are
+            // dropped rather than counted twice.
+            const selfDID = normalizeDID(params.localDID);
+            const seen = new Set();
+            const replies = [];
+            for (const reply of gathered.flat()){
+                const senderDID = normalizeDID(reply.senderDID);
+                if (senderDID === selfDID || seen.has(senderDID)) {
+                    continue;
+                }
+                seen.add(senderDID);
+                // The wire result is a bare `InstanceStatus[]`; the body names no device.
+                replies.push({
+                    senderDID,
+                    instances: reply.value ?? []
+                });
+            }
+            return replies;
+        },
+        async requestWorkflow (groupID, targetDID, method, param) {
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null || groupSet.size === 0) {
+                throw new Error(`No hub-peer to reach ${targetDID} for group ${groupID}`);
+            }
+            // First bound hub wins; the rest are fallthrough routes to the SAME
+            // mailbox, tried only when a hub throws before delivering. A returned
+            // refusal is the answer and stops here — it is never a reason to re-send,
+            // which for a mutating command would risk a second execution.
+            let lastError;
+            for (const hubURL of groupSet){
+                const peer = peers.get(peerKey(groupID, hubURL));
+                if (peer == null) {
+                    continue;
+                }
+                try {
+                    return await throughRotation(async ()=>{
+                        // Generic invoker: the enkaku client types `request`'s arg per
+                        // method, but this carries any of the five directed procedures, so
+                        // it is reached through a loose surface and the typed pluginAPI
+                        // method shapes the result. The `{ param }` wrapping is the enkaku
+                        // request-arg envelope, as `.to(...).request(m, { param })` elsewhere.
+                        const client = await peer.protocol('workflow').to(targetDID);
+                        return await client.request(method, {
+                            param
+                        });
+                    }, `request ${method}`, logger);
+                } catch (error) {
+                    lastError = error;
+                    logger?.warn('workflow request failed on a hub', {
+                        groupID,
+                        hubURL,
+                        method,
+                        error
+                    });
+                }
+            }
+            throw lastError ?? new Error(`No hub-peer to reach ${targetDID} for group ${groupID}`);
+        },
         async removeGroup (groupID) {
             joined.delete(groupID);
             await tunnelListeners?.removeGroup(groupID);
@@ -1160,6 +1297,23 @@ export function createGroupPeerManager(params) {
             await serviceTunnelListeners?.reconcile(groupID);
         },
         broadcast: broadcastToPeers,
+        reauthorize (groupID) {
+            // Ask every hub-peer of the group to re-drive any subscription its hub refused. The one case
+            // this exists for: a device subscribes its group topics the instant it joins (`addGroup` ->
+            // `createPeer`), before the APP-level authorization that gates them at the hub has landed, so
+            // the hub answers `AuthorizationDeniedError` and the peer's mux latches it permanent (a busy
+            // retry against an answer would be worse). The app cannot un-latch it by re-joining — the
+            // roster is invisible to this layer — so once the app knows the device is authorized (its
+            // membership row has replicated) it calls this. `GroupPeer.reauthorize()` is synchronous and
+            // idempotent, and a no-op on a peer holding nothing refused, so this just fans it over the
+            // live hub-peers with no error surface of its own. The loopback peer never subscribes a hub,
+            // so it is deliberately skipped.
+            const groupSet = bindings.get(groupID);
+            if (groupSet == null) return;
+            for (const hubURL of groupSet){
+                peers.get(peerKey(groupID, hubURL))?.reauthorize();
+            }
+        },
         async selectCommitPeer (groupID) {
             const groupSet = bindings.get(groupID);
             if (groupSet == null || groupSet.size === 0) {
@@ -1306,7 +1460,10 @@ export function createGroupPeerManager(params) {
                     return [];
                 }
                 try {
-                    return await peer.protocol('control').gather('control/ledgerCatchup', {}, gatherOptions);
+                    return await peer.protocol('control').gather('control/ledgerCatchup', {
+                        param: {},
+                        ...gatherOptions
+                    });
                 } catch (error) {
                     logger?.warn('ledger catch-up gather failed on a hub', {
                         groupID,