@kubun/plugin-p2p 0.15.0 → 0.16.0

package/lib/hub/wiring.js

@@ -44,6 +44,12 @@ export function setupHubRelay(params) {
     };
     const presence = async ()=>(await ready).presence;
     const retryHubs = async ()=>await (await ready).retryHubs();
+    const discoverWorkflows = async (groupID, options)=>await (await ready).discoverWorkflows(groupID, options);
+    const requestWorkflow = async (groupID, targetDID, method, param)=>await (await ready).requestWorkflow(groupID, targetDID, method, param);
+    const reauthorize = async (groupID)=>{
+        ;
+        (await ready).reauthorize(groupID);
+    };
     const syncTransportTo = async (groupID, peerDID)=>{
         const hub = (await ready).tunnelHub(groupID);
         if (hub == null) {
@@ -85,6 +91,12 @@ export function setupHubRelay(params) {
             graphStore,
             graph,
             hlc,
+            ...params.ready != null ? {
+                ready: params.ready
+            } : {},
+            ...params.getWorkflowAPI != null ? {
+                getWorkflowAPI: params.getWorkflowAPI
+            } : {},
             maxDriftMS,
             localDID: identity.id,
             identity,
@@ -117,6 +129,9 @@ export function setupHubRelay(params) {
             ...params.services != null ? {
                 services: params.services
             } : {},
+            ...params.cache != null ? {
+                cache: params.cache
+            } : {},
             tunnelIdleTimeoutMs: tunnelIdleTimeoutMs ?? DEFAULT_TUNNEL_IDLE_TIMEOUT_MS
         });
         unsubscribes.push(emitter.on('groupJoined', (group)=>manager.addGroup(group.id).catch((error)=>{
@@ -184,6 +199,9 @@ export function setupHubRelay(params) {
         requestLedgerCatchup,
         presence,
         retryHubs,
+        discoverWorkflows,
+        requestWorkflow,
+        reauthorize,
         syncTransportTo,
         serviceTransportTo,
         dispose: async ()=>{

package/lib/index.js

@@ -1,7 +1,7 @@
 import { ServerTransport } from '@enkaku/http-serve';
 import { Server } from '@enkaku/server';
 import { DirectTransports } from '@enkaku/transport';
-import { isFullIdentity } from '@kokuin/token';
+import { createInMemoryDIDCache, isFullIdentity } from '@kokuin/token';
 import { createDeviceAuthority } from '@kubun/credential';
 import { resolveAllowedOrigin } from '@kubun/http-util';
 import { getGraphStore } from '@kubun/store-graph';
@@ -107,11 +107,10 @@ export function createP2PPlugin(options) {
         }
         const identity = params.identity;
         // The engine's single device-wide clock. Sharing it across the p2p group/
-        // circle/member metadata paths (context, GroupManager, BroadcastService)
-        // keeps every write from this device on one monotonic counter, so two
-        // writes in the same millisecond mint strictly-increasing timestamps rather
-        // than identical ones (the second of which would silently lose under
-        // last-writer-wins).
+        // circle/member metadata paths keeps every write from this device on one
+        // monotonic counter, so two writes in the same millisecond mint
+        // strictly-increasing timestamps rather than identical ones (the second of
+        // which would silently lose under last-writer-wins).
         const hlc = params.hlc;
         // Computed up front so SyncManager + sync handlers + the hub-relay
         // BroadcastService all see the same receive policy. Hot-path invariant:
@@ -199,6 +198,13 @@ export function createP2PPlugin(options) {
         const peerConnections = new PeerConnectionRegistry({
             logger: params.getLogger('peer-connections')
         });
+        // One plugin-lifetime DID cache, shared by every peer-lane Server. The
+        // tunnel listeners seed it from each group's MLS roster (a co-member's
+        // authenticated leaf long form), so a freshly-spawned per-session Server
+        // resolves a co-member's short-form `did:peer:4` issuer instead of defaulting
+        // its own empty cache. Content-addressed and monotonic — a stale entry is
+        // harmless, and it survives no process restart by design (re-seeded on bind).
+        const didCache = createInMemoryDIDCache();
         // The p2p plugin manages its own Enkaku server for sync handlers,
         // separate from the graph service's server.
         const syncServers = [];
@@ -222,6 +228,7 @@ export function createP2PPlugin(options) {
                 transports: [
                     directTransports.server
                 ],
+                cache: didCache,
                 signal
             });
             syncServers.push(server);
@@ -290,18 +297,33 @@ export function createP2PPlugin(options) {
             runtime: params.runtime,
             db: params.db,
             hlc,
+            // The engine's identity gate, forwarded to the presence coordinator so a
+            // self-started announce waits for verification before it mints.
+            ready: ()=>params.engine.ready(),
+            // A thunk, not the resolved value: `getWorkflowAPI` is defined further down
+            // this factory body, so it is only in the temporal dead zone until the body
+            // finishes — and the manager invokes this on peer creation, long after.
+            getWorkflowAPI: ()=>getWorkflowAPI(),
             maxDriftMS: params.maxDriftMS,
             graph: params.graph,
             emitter,
             createHubClient,
             registry,
             // Re-drive a lost `ledger` commit's surviving tokens through the group
-            // manager's own ledger write path, so the seam stays a consumer of it.
-            buildLedgerRedrive: (groupID, tokens, requestID)=>groupManager.buildEnactLedgerCommit({
+            // manager's own ledger write path, so the seam stays a consumer of it. The
+            // redrive is a self-start (the hub relay, not a request), so its commit
+            // build waits behind `ready()` before it mints under the engine's clock.
+            buildLedgerRedrive: (groupID, tokens, requestID)=>{
+                const build = groupManager.buildEnactLedgerCommit({
                     groupID,
                     tokens,
                     requestID
-                }),
+                });
+                return async ()=>{
+                    await params.engine.ready();
+                    return build();
+                };
+            },
             logger: hubRelayLogger,
             storeUnreadable: receiveConfig.storeUnreadable,
             defaultAccessLevel,
@@ -324,7 +346,9 @@ export function createP2PPlugin(options) {
             ...serviceServe != null ? {
                 serviceServe,
                 services: serviceConfig
-            } : {}
+            } : {},
+            // The shared roster-seeded cache reaches the tunnel listeners here.
+            cache: didCache
         });
         // Turn a `tunnel://<groupID>/<peerDID>` route into a live session over the
         // group's hub. Until this existed the scheme parsed and then failed at
@@ -424,30 +448,47 @@ export function createP2PPlugin(options) {
         // use, executed on behalf of the verified caller against the plugin's own
         // DB (peer procedures run outside an engine transaction; `joinGroup` manages
         // its own inner transaction). No MLS logic is reimplemented here.
+        // The inbound peer dance stamps group/roster/ledger metadata under the
+        // engine's clock outside any GraphQL write entry, so each runner is a
+        // self-start driver: it awaits `ready()` before touching the deps that mint.
+        // `ready()` is resolved for a booted engine, so this only delays a dance that
+        // arrives in the window before identity verification settles.
         const peerHandlers = createPeerHandlers({
             db: params.db,
             identity,
             logger: params.getLogger('peer-handlers'),
             autoAcceptPeers: options?.autoAcceptPeers,
-            runPrepareJoin: (callerDID)=>createJoinContext(// Out-of-band peer-handler context for the verified caller; the join ops
+            runPrepareJoin: async (callerDID)=>{
+                await params.engine.ready();
+                return createJoinContext(// Out-of-band peer-handler context for the verified caller; the join ops
                 // never consult the authority, so a self-scoped device authority fits.
                 {
                     viewerDID: callerDID,
                     credentialAuthority: createDeviceAuthority(callerDID)
-                }, buildContextDeps(params.db)).prepareRequest(),
-            runCompleteJoin: (callerDID, invitePayload)=>createJoinContext({
+                }, buildContextDeps(params.db)).prepareRequest();
+            },
+            runCompleteJoin: async (callerDID, invitePayload)=>{
+                await params.engine.ready();
+                return createJoinContext({
                     viewerDID: callerDID,
                     credentialAuthority: createDeviceAuthority(callerDID)
-                }, buildContextDeps(params.db)).complete(invitePayload),
-            runInvite: (callerDID, groupID, joinRequest)=>serveGroupInvite(buildContextDeps(params.db), {
+                }, buildContextDeps(params.db)).complete(invitePayload);
+            },
+            runInvite: async (callerDID, groupID, joinRequest)=>{
+                await params.engine.ready();
+                return serveGroupInvite(buildContextDeps(params.db), {
                     callerDID,
                     groupID,
                     joinRequest
-                }),
-            runPushControl: (callerDID, param)=>servePushControl(buildContextDeps(params.db), {
+                });
+            },
+            runPushControl: async (callerDID, param)=>{
+                await params.engine.ready();
+                return servePushControl(buildContextDeps(params.db), {
                     callerDID,
                     ...param
-                })
+                });
+            }
         });
         // Blob transfer control-lane handlers, mounted on the same peer server.
         const blobHandlers = createBlobHandlers({
@@ -557,6 +598,7 @@ export function createP2PPlugin(options) {
             // runners do: the scopes an automatic catch-up asks for cannot drift from
             // the ones an explicit one asks for if there is only one implementation.
             catchUpWithBestPeer: (groupID)=>createSyncContext(null, buildContextDeps(params.db)).catchUpWithBestPeer(groupID),
+            reauthorize: (groupID)=>hub.reauthorize(groupID),
             listPeerDevices: (groupID)=>createSyncContext(null, buildContextDeps(params.db)).listPeerDevices(groupID),
             onSyncEvent: (callback)=>syncManager.onSyncEvent(callback),
             onHubServerDIDChanged: (listener)=>emitter.on('hubServerDIDChanged', listener),
@@ -567,6 +609,37 @@ export function createP2PPlugin(options) {
                 await (await hub.presence()).setProfile(profile);
             },
             getLocalPeerProfile: async ()=>await (await hub.presence()).getProfile(),
+            // The typed workflow control plane: `groupID` selects the peers, the hub
+            // wiring handles the multi-hub fan-out (discover) and directed `.to()`
+            // request (the rest). The wire results are shaped to the contract types
+            // here; a business refusal on a command travels as data, and a caller
+            // helper (plugin-workflow) reconstitutes it into a throw.
+            discoverWorkflows: (groupID, options)=>hub.discoverWorkflows(groupID, options),
+            listWorkflows: async (groupID, targetDID)=>// `workflow/list` takes no fields but its param schema is a (closed) object,
+                // so an omitted param serializes to an invalid request frame — pass `{}`.
+                await hub.requestWorkflow(groupID, targetDID, 'workflow/list', {}),
+            workflowStatus: async (groupID, targetDID, instanceID)=>await hub.requestWorkflow(groupID, targetDID, 'workflow/status', {
+                    instanceID
+                }),
+            enqueueWorkflow: async (groupID, targetDID, name, params, opts)=>await hub.requestWorkflow(groupID, targetDID, 'workflow/enqueue', {
+                    name,
+                    params,
+                    // A stable idempotency key makes the cross-hub retry safe: a directed
+                    // request can throw on the RESPONSE leg (the target already enqueued,
+                    // but the reply was lost), and the retry re-sends to the same mailbox.
+                    // Under one key the target returns the existing instance instead of
+                    // creating a second. A caller-supplied key wins; else one per call.
+                    opts: {
+                        ...opts,
+                        idempotencyKey: opts?.idempotencyKey ?? crypto.randomUUID()
+                    }
+                }),
+            cancelWorkflow: async (groupID, targetDID, instanceID)=>await hub.requestWorkflow(groupID, targetDID, 'workflow/cancel', {
+                    instanceID
+                }),
+            retryWorkflow: async (groupID, targetDID, instanceID)=>await hub.requestWorkflow(groupID, targetDID, 'workflow/retry', {
+                    instanceID
+                }),
             gatherPeers: async (groupID, options)=>await (await hub.presence()).gather(groupID, options),
             refreshPeerPresence: async (groupID, options)=>await (await hub.presence()).refresh(groupID, options),
             retryHubConnection: async ()=>await hub.retryHubs(),
@@ -629,7 +702,8 @@ export function createP2PPlugin(options) {
                     logger: params.getLogger('sync-http-server'),
                     transports: [
                         httpSyncTransport
-                    ]
+                    ],
+                    cache: didCache
                 });
                 syncServers.push(httpSyncServer);
                 httpAPI.registerProtocol(protocolName, httpSyncTransport.fetch.bind(httpSyncTransport));
@@ -672,7 +746,8 @@ export function createP2PPlugin(options) {
                     logger: params.getLogger('peer-http-server'),
                     transports: [
                         httpPeerTransport
-                    ]
+                    ],
+                    cache: didCache
                 });
                 httpAPI.registerProtocol('peer', httpPeerTransport.fetch.bind(httpPeerTransport));
             })();

package/lib/sync/hub-tunnel-service-listener.d.ts

@@ -1,5 +1,6 @@
 import type { ServerTransportOf } from '@enkaku/protocol';
 import type { Server } from '@enkaku/server';
+import type { DIDCache } from '@kokuin/token';
 import type { Logger } from '@kubun/logger';
 import type { ServiceConfig, ServiceProtocol } from '@kubun/plugin-service-api';
 import { type MailboxHub } from '@kumiai/hub-tunnel';
@@ -16,6 +17,8 @@ export type ServeService = (params: {
     transport: ServerTransportOf<ServiceProtocol>;
     services: Record<string, ServiceConfig>;
     requireAuth?: false;
+    /** Shared, roster-seeded DID cache forwarded to the served Server. */
+    cache?: DIDCache;
 }) => Server<ServiceProtocol>;
 /**
  * The injected {@link ServeService} was called before the `service-server`
@@ -55,6 +58,12 @@ export type HubTunnelServiceListenerParams = {
     serve: ServeService;
     /** Which services to serve, forwarded verbatim to {@link serve} on every spawn. */
     services: Record<string, ServiceConfig>;
+    /**
+     * Shared, roster-seeded DID cache forwarded to {@link serve} on every spawn,
+     * so a co-member's short-form `did:peer:4` issuer resolves on the served
+     * Server.
+     */
+    cache?: DIDCache;
     idleTimeoutMs?: number;
     logger?: Logger;
 };

package/lib/sync/hub-tunnel-service-listener.js

@@ -40,6 +40,7 @@ import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
     #runtime;
     #serve;
     #services;
+    #cache;
     #idleTimeoutMs;
     #logger;
     #started = false;
@@ -64,6 +65,7 @@ import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
         this.#runtime = params.runtime;
         this.#serve = params.serve;
         this.#services = params.services;
+        this.#cache = params.cache;
         this.#idleTimeoutMs = params.idleTimeoutMs;
         this.#logger = params.logger;
     }
@@ -225,7 +227,10 @@ import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
         try {
             server = this.#serve({
                 transport,
-                services: this.#services
+                services: this.#services,
+                ...this.#cache != null ? {
+                    cache: this.#cache
+                } : {}
             });
         } catch (error) {
             await transport.dispose().catch(()=>{

package/lib/sync/hub-tunnel-sync-listener.d.ts

@@ -1,5 +1,5 @@
 import { type ProcedureHandlers } from '@enkaku/server';
-import type { OwnIdentity } from '@kokuin/token';
+import type { DIDCache, OwnIdentity } from '@kokuin/token';
 import type { Logger } from '@kubun/logger';
 import { type MailboxHub, type ObservabilityEventListener } from '@kumiai/hub-tunnel';
 import type { Runtime } from '@sozai/runtime';
@@ -26,6 +26,13 @@ export type HubTunnelSyncListenerParams = {
      * keeps one generator across the whole plugin.
      */
     runtime: Runtime;
+    /**
+     * Shared, roster-seeded DID cache handed to every spawned session's Server, so
+     * a co-member's short-form `did:peer:4` issuer resolves without a resolver the
+     * blind hub lane has none of. A fresh per-session Server would otherwise
+     * default its own empty cache.
+     */
+    cache?: DIDCache;
     idleTimeoutMs?: number;
     reconnectTimeoutMs?: number;
     inboxCapacity?: number;

package/lib/sync/hub-tunnel-sync-listener.js

@@ -15,6 +15,7 @@ export class HubTunnelSyncListener {
     #identity;
     #syncHandlers;
     #runtime;
+    #cache;
     #idleTimeoutMs;
     #reconnectTimeoutMs;
     #inboxCapacity;
@@ -42,6 +43,7 @@ export class HubTunnelSyncListener {
         this.#identity = params.identity;
         this.#syncHandlers = params.syncHandlers;
         this.#runtime = params.runtime;
+        this.#cache = params.cache;
         this.#idleTimeoutMs = params.idleTimeoutMs;
         this.#reconnectTimeoutMs = params.reconnectTimeoutMs;
         this.#inboxCapacity = params.inboxCapacity;
@@ -203,7 +205,10 @@ export class HubTunnelSyncListener {
             },
             transports: [
                 transport
-            ]
+            ],
+            ...this.#cache != null ? {
+                cache: this.#cache
+            } : {}
         });
         const session = {
             transport,

package/lib/sync/service-tunnel-listeners.d.ts

@@ -1,4 +1,4 @@
-import type { OwnIdentity } from '@kokuin/token';
+import type { DIDCache, OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { ServiceConfig } from '@kubun/plugin-service-api';
@@ -17,6 +17,12 @@ export type ServiceTunnelListenersParams = {
     serve: ServeService;
     /** Which services to serve, forwarded verbatim to `serve` on every spawn. */
     services: Record<string, ServiceConfig>;
+    /**
+     * Shared, plugin-lifetime DID cache. Seeded from each group's roster on every
+     * reconcile and forwarded to `serve` on every spawn, so a co-member's
+     * short-form `did:peer:4` issuer resolves on the served Server.
+     */
+    cache?: DIDCache;
     /** The group's device-wide drain, or `undefined` when no hub is bound. */
     tunnelHub: (groupID: string) => MailboxHub | undefined;
     logger?: Logger;

package/lib/sync/service-tunnel-listeners.js

@@ -1,5 +1,6 @@
 import { normalizeDID } from '@kokuin/token';
 import { getP2PStore } from '@kubun/store-p2p';
+import { seedDIDCacheFromRoster } from '../groups/did-cache-seed.js';
 import { HubTunnelServiceListener } from './hub-tunnel-service-listener.js';
 /**
  * The answering half of the service tunnel — one `HubTunnelServiceListener` per
@@ -63,6 +64,20 @@ import { HubTunnelServiceListener } from './hub-tunnel-service-listener.js';
         }
         attachedHubs.set(groupID, hub);
         attachedEpochs.set(groupID, epoch);
+        // Bind and membership change both land here, so this is the one seam where a
+        // co-member's roster long form is refreshed into the shared cache before any
+        // service session that must resolve its short-form issuer can spawn.
+        if (params.cache != null) {
+            await seedDIDCacheFromRoster({
+                cache: params.cache,
+                registry: params.registry,
+                groupID,
+                stores: params.stores,
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+        }
         const members = await store.listGroupMembers(groupID);
         const wanted = new Set(members.map((member)=>normalizeDID(member.member_did)).filter((did)=>did !== selfDID));
         let group = listeners.get(groupID);
@@ -105,6 +120,9 @@ import { HubTunnelServiceListener } from './hub-tunnel-service-listener.js';
                 runtime: params.runtime,
                 serve: params.serve,
                 services: params.services,
+                ...params.cache != null ? {
+                    cache: params.cache
+                } : {},
                 ...params.idleTimeoutMs != null ? {
                     idleTimeoutMs: params.idleTimeoutMs
                 } : {},

package/lib/sync/sync-manager.d.ts

@@ -1,4 +1,4 @@
-import { type Identity, type SigningIdentity } from '@kokuin/token';
+import { type Identity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
@@ -76,10 +76,6 @@ export declare class SyncManager {
     #private;
     constructor(params: SyncManagerParams);
     get peerRegistry(): PeerRegistry;
-    /**
-     * Configure the signing identity used for sync operations.
-     */
-    setIdentity(identity: SigningIdentity): void;
     /**
      * Configure the resolver for the transports built locally rather than dialled:
      * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose

package/lib/sync/sync-manager.js

@@ -36,11 +36,6 @@ export class SyncManager {
         return this.#peerRegistry;
     }
     /**
-   * Configure the signing identity used for sync operations.
-   */ setIdentity(identity) {
-        this.#identity = identity;
-    }
-    /**
    * Configure the resolver for the transports built locally rather than dialled:
    * `direct://` (in-process) and `tunnel://` (relayed by the group's hub, whose
    * group id arrives as the resolver's `route`).

package/lib/sync/tunnel-listeners.d.ts

@@ -1,5 +1,5 @@
 import type { ProcedureHandlers } from '@enkaku/server';
-import type { OwnIdentity } from '@kokuin/token';
+import type { DIDCache, OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { MailboxHub } from '@kumiai/hub-tunnel';
@@ -13,6 +13,12 @@ export type TunnelListenersParams = {
     localDID: string;
     runtime: Runtime;
     syncHandlers: ProcedureHandlers<SyncProtocol>;
+    /**
+     * Shared, plugin-lifetime DID cache. Seeded from each group's roster on every
+     * reconcile (bind and membership change) and handed to every spawned session's
+     * Server, so a co-member's short-form `did:peer:4` issuer resolves there.
+     */
+    cache?: DIDCache;
     /** The group's device-wide drain, or `undefined` when no hub is bound. */
     tunnelHub: (groupID: string) => MailboxHub | undefined;
     logger?: Logger;

package/lib/sync/tunnel-listeners.js

@@ -1,5 +1,6 @@
 import { normalizeDID } from '@kokuin/token';
 import { getP2PStore } from '@kubun/store-p2p';
+import { seedDIDCacheFromRoster } from '../groups/did-cache-seed.js';
 import { HubTunnelSyncListener } from './hub-tunnel-sync-listener.js';
 /**
  * The answering half of the tunnel: one listener per co-member per group, so a
@@ -73,6 +74,20 @@ import { HubTunnelSyncListener } from './hub-tunnel-sync-listener.js';
         }
         attachedHubs.set(groupID, hub);
         attachedEpochs.set(groupID, epoch);
+        // Bind and membership change both land here, so this is the one seam where a
+        // co-member's roster long form is refreshed into the shared cache before any
+        // session that must resolve its short-form issuer can spawn.
+        if (params.cache != null) {
+            await seedDIDCacheFromRoster({
+                cache: params.cache,
+                registry: params.registry,
+                groupID,
+                stores: params.stores,
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+        }
         const members = await store.listGroupMembers(groupID);
         const wanted = new Set(members.map((member)=>normalizeDID(member.member_did)).filter((did)=>did !== selfDID));
         let group = listeners.get(groupID);
@@ -115,6 +130,9 @@ import { HubTunnelSyncListener } from './hub-tunnel-sync-listener.js';
                 identity: params.identity,
                 syncHandlers: params.syncHandlers,
                 runtime: params.runtime,
+                ...params.cache != null ? {
+                    cache: params.cache
+                } : {},
                 ...params.idleTimeoutMs != null ? {
                     idleTimeoutMs: params.idleTimeoutMs
                 } : {},

package/lib/types.d.ts

@@ -1,4 +1,5 @@
 import type { ClientTransportOf } from '@enkaku/protocol';
+import type { WorkflowControlPlaneAPI } from '@kubun/plugin-p2p-api';
 import type { ServiceProtocol } from '@kubun/plugin-service-api';
 import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
 import type { AccessLevel } from '@kubun/store-graph';
@@ -1082,7 +1083,7 @@ export type PeerGatherOptions = {
  * of the logs, and nothing branches on it.
  */
 export type PresenceReason = 'hub-connected' | 'epoch-changed' | 'app-window-pruned' | 'requested';
-export type SyncPluginAPI = {
+export type SyncPluginAPI = WorkflowControlPlaneAPI & {
     /** Resolves when the HTTP sync transport is registered (only present when http option is enabled). */
     syncReady?: Promise<void>;
     /**
@@ -1109,6 +1110,19 @@ export type SyncPluginAPI = {
      * decides who, and an explicit `syncPeer` ignores the ranking entirely.
      */
     catchUpWithBestPeer(groupID: string): Promise<PeerCatchUpData>;
+    /**
+     * Re-drive any group subscription this device's hub-peers latched as refused.
+     *
+     * A device subscribes its group topics the instant it joins, before the
+     * APPLICATION-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). This layer cannot
+     * see the app's authorization state, so it cannot know on its own when to ask
+     * again; the app calls this once it knows the device is authorized (e.g. its
+     * membership row has replicated after pairing completes). Idempotent and a
+     * no-op when nothing is refused — safe to call on every authorization change.
+     */
+    reauthorize(groupID: string): Promise<void>;
     /**
      * Every device this one has heard announce in the group — the projection, and
      * never a liveness answer. {@link SyncPluginAPI.gatherPeers} is what says who

package/lib/types.js

@@ -1 +1,5 @@
+// The six caller-facing workflow control-plane methods (discover/list/status/
+// enqueue/cancel/retry, each keyed by `groupID`) are contributed by
+// WorkflowControlPlaneAPI so this plugin's public surface and the type-only
+// contract plugin-workflow imports cannot drift.
 export { };