@kubun/plugin-p2p 0.13.1 → 0.15.0

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

@@ -6,6 +6,8 @@ import { createGroupPeer, RecoveryRequiredError } from '@kumiai/rpc';
 import { createHubLike } from '../hub/hub-like.js';
 import { createLoopbackLogHub } from '../hub/loopback-log-hub.js';
 import { createHubServerDIDResolver } from '../hub/server-did.js';
+import { HubTunnelServiceProvider } from '../sync/hub-tunnel-service-provider.js';
+import { createServiceTunnelListeners } from '../sync/service-tunnel-listeners.js';
 import { createTunnelListeners } from '../sync/tunnel-listeners.js';
 import { applyAccessDefaultSetToken } from './access-default-apply.js';
 import { createAnchorStore } from './anchor-store.js';
@@ -15,6 +17,7 @@ import { reprojectGroupSettings } from './circle-projection.js';
 import { adoptCommitJournalBlob, readJournalRequestID, settleLostControlRequest } from './commit-adoption.js';
 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 { createGroupMLS } from './group-mls.js';
@@ -112,6 +115,14 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
                 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
+            });
+            return;
         default:
             {
                 // Exhaustiveness gate. A broadcast type with no case here used to fall off
@@ -466,12 +477,19 @@ export function createGroupPeerManager(params) {
         // `hasStore` because `getStore` on an unregistered name throws, and a device
         // with no credential plugin must still bind its peers.
         const credentialStore = params.stores.hasStore(CREDENTIAL_STORE) ? await getCredentialStore(params.stores) : undefined;
+        // Delegate-wrapping admission deps, sourced from the engine's controller
+        // resolver. Absent seam → empty deps → fail-closed delegated wrapping.
+        const credentialWrappingDeps = await createCredentialWrappingDeps(params.stores, params.controllerResolverFor);
         return {
             p2pStore,
             delegationStore,
             ...credentialStore != null ? {
                 credentialStore
             } : {},
+            ...credentialWrappingDeps.controllerResolver != null && credentialWrappingDeps.revocationChecker != null ? {
+                credentialControllerResolver: credentialWrappingDeps.controllerResolver,
+                credentialRevocationChecker: credentialWrappingDeps.revocationChecker
+            } : {},
             graphStore: params.graphStore,
             graph: params.graph,
             selfDID: params.localDID,
@@ -811,6 +829,9 @@ export function createGroupPeerManager(params) {
     // Declared ahead of the presence it is triggered from, and assigned below once
     // the hub lookup it needs exists.
     let tunnelListeners;
+    // Same shape, service lane — see the assignment below. Reconciled on every
+    // trigger `tunnelListeners` is, and disposed alongside it in `stop`.
+    let serviceTunnelListeners;
     const presence = createPeerPresence({
         stores: params.stores,
         localDID: params.localDID,
@@ -821,6 +842,7 @@ export function createGroupPeerManager(params) {
         onProfileSet: ()=>{
             for (const groupID of joined){
                 void tunnelListeners?.reconcile(groupID);
+                void serviceTunnelListeners?.reconcile(groupID);
             }
         },
         getGroupEpoch: (groupID)=>params.registry.groupEpoch(groupID) ?? undefined,
@@ -902,6 +924,25 @@ export function createGroupPeerManager(params) {
             idleTimeoutMs: params.tunnelIdleTimeoutMs
         } : {}
     });
+    serviceTunnelListeners = params.serviceServe == null || params.services == null || tunnelRuntime == null ? undefined : createServiceTunnelListeners({
+        stores: params.stores,
+        registry: params.registry,
+        identity: params.identity,
+        localDID: params.localDID,
+        runtime: tunnelRuntime,
+        serve: params.serviceServe,
+        services: params.services,
+        tunnelHub: (groupID)=>{
+            const hubURL = bindings.get(groupID)?.values().next().value;
+            return hubURL == null ? undefined : getHubLike(hubURL);
+        },
+        ...logger != null ? {
+            logger
+        } : {},
+        ...params.tunnelIdleTimeoutMs != null ? {
+            idleTimeoutMs: params.tunnelIdleTimeoutMs
+        } : {}
+    });
     // TRIGGER — epoch change. A member added at this epoch was never on the old
     // topic, so every earlier announcement is unreachable to it: the rotation is
     // exactly when the group needs to be told again who is here.
@@ -918,6 +959,7 @@ export function createGroupPeerManager(params) {
     triggerUnsubscribes.push(params.registry.onEpochChanged((groupID)=>{
         presence.scheduleAnnounce(groupID, 'epoch-changed');
         void tunnelListeners?.reconcile(groupID);
+        void serviceTunnelListeners?.reconcile(groupID);
     }));
     const addGroup = async (groupID)=>{
         joined.add(groupID);
@@ -940,6 +982,7 @@ export function createGroupPeerManager(params) {
         });
         // After the peers, so the binding the listeners read exists.
         await tunnelListeners?.reconcile(groupID);
+        await serviceTunnelListeners?.reconcile(groupID);
     };
     /** Groups with a catch-up round already open, so the triggers cannot stack. */ const policyCatchupInFlight = new Set();
     /** Groups already asked once on connect — see {@link schedulePolicyCatchup}. */ const policyCatchupAsked = new Set();
@@ -1074,6 +1117,7 @@ export function createGroupPeerManager(params) {
         async removeGroup (groupID) {
             joined.delete(groupID);
             await tunnelListeners?.removeGroup(groupID);
+            await serviceTunnelListeners?.removeGroup(groupID);
             const groupSet = bindings.get(groupID);
             const urls = groupSet != null ? [
                 ...groupSet
@@ -1085,6 +1129,7 @@ export function createGroupPeerManager(params) {
         },
         async reconcileTunnelListeners (groupID) {
             await tunnelListeners?.reconcile(groupID);
+            await serviceTunnelListeners?.reconcile(groupID);
         },
         async addBinding (groupID, hubURL) {
             if (!joined.has(groupID)) {
@@ -1105,12 +1150,14 @@ export function createGroupPeerManager(params) {
             // A group with no hub could not be dialled at all, so this is where its
             // members become answerable.
             await tunnelListeners?.reconcile(groupID);
+            await serviceTunnelListeners?.reconcile(groupID);
         },
         async removeBinding (groupID, hubURL) {
             await disposePeer(groupID, hubURL);
             // The listeners hold the drain of whichever hub is bound; the one they were
             // built on may be the one that just left.
             await tunnelListeners?.reconcile(groupID);
+            await serviceTunnelListeners?.reconcile(groupID);
         },
         broadcast: broadcastToPeers,
         async selectCommitPeer (groupID) {
@@ -1331,6 +1378,29 @@ export function createGroupPeerManager(params) {
             const hubURL = bindings.get(groupID)?.values().next().value;
             return hubURL == null ? undefined : getHubLike(hubURL);
         },
+        async serviceTransportTo (groupID, peerDID) {
+            const hub = this.tunnelHub(groupID);
+            // `tunnelRuntime` mirrors `params.runtime`, which is optional here (a test
+            // harness may build a manager without one) — a caller with no runtime has
+            // no id generator to hand the transport, so there is no session to build.
+            if (hub == null || tunnelRuntime == null) {
+                return undefined;
+            }
+            return new HubTunnelServiceProvider({
+                hub,
+                registry: params.registry,
+                groupID,
+                localDID: params.localDID,
+                peerDID,
+                runtime: tunnelRuntime,
+                ...params.tunnelIdleTimeoutMs != null ? {
+                    idleTimeoutMs: params.tunnelIdleTimeoutMs
+                } : {},
+                ...logger != null ? {
+                    logger: logger.getChild('service-tunnel-session')
+                } : {}
+            });
+        },
         async retryHubs () {
             const live = [
                 ...hubLikes.values()
@@ -1348,6 +1418,7 @@ export function createGroupPeerManager(params) {
             // Before the hubs go: each listener holds a subscription on one of them,
             // and its spawn loop re-arms until it is told to stop.
             await tunnelListeners?.dispose();
+            await serviceTunnelListeners?.dispose();
             for (const off of triggerUnsubscribes.splice(0)){
                 try {
                     off();

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

@@ -310,6 +310,29 @@ export declare const controlProtocol: {
             readonly additionalProperties: false;
         };
     };
+    readonly 'control/credentialKeyManifest': {
+        readonly type: "event";
+        readonly retain: "log";
+        readonly description: "A grantor's advisory record of the key set it granted a recipient (the readiness union). `manifest` is the grantor's signed token; `delegationTokens` proves its administer chain over the owner. Group-wide because the receiver keys the row on the manifest's own owner/recipient/grantor. The manifest authorizes nothing — the receiver's gate keeps a bogus one out of the store.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly manifest: {
+                    readonly type: "string";
+                    readonly description: "The grantor's signed manifest token; its issuer is the authoritative grantor.";
+                };
+                readonly delegationTokens: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "The grantor's administer-chain delegation tokens, closest-to-grantor first. Empty when the grantor is the owner.";
+                };
+            };
+            readonly required: readonly ["manifest", "delegationTokens"];
+            readonly additionalProperties: false;
+        };
+    };
     readonly 'control/groupLeaveRequest': {
         readonly type: "event";
         readonly retain: "ephemeral";
@@ -494,6 +517,7 @@ export type DelegationRevokeData = FromSchema<(typeof controlProtocol)['control/
 export type AccessDefaultSetData = FromSchema<(typeof controlProtocol)['control/accessDefaultSet']['data']>;
 export type AccessDefaultRemoveData = FromSchema<(typeof controlProtocol)['control/accessDefaultRemove']['data']>;
 export type CredentialKeyGrantData = FromSchema<(typeof controlProtocol)['control/credentialKeyGrant']['data']>;
+export type CredentialKeyManifestData = FromSchema<(typeof controlProtocol)['control/credentialKeyManifest']['data']>;
 export type GroupLeaveRequestData = FromSchema<(typeof controlProtocol)['control/groupLeaveRequest']['data']>;
 export type MutationApplyData = FromSchema<(typeof syncProtocol)['sync/mutationApply']['data']>;
 export type PeerAnnounceData = FromSchema<(typeof peerProtocol)['peer/announce']['data']>;
@@ -806,6 +830,29 @@ export declare const groupProtocols: {
                 readonly additionalProperties: false;
             };
         };
+        readonly 'control/credentialKeyManifest': {
+            readonly type: "event";
+            readonly retain: "log";
+            readonly description: "A grantor's advisory record of the key set it granted a recipient (the readiness union). `manifest` is the grantor's signed token; `delegationTokens` proves its administer chain over the owner. Group-wide because the receiver keys the row on the manifest's own owner/recipient/grantor. The manifest authorizes nothing — the receiver's gate keeps a bogus one out of the store.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly manifest: {
+                        readonly type: "string";
+                        readonly description: "The grantor's signed manifest token; its issuer is the authoritative grantor.";
+                    };
+                    readonly delegationTokens: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "The grantor's administer-chain delegation tokens, closest-to-grantor first. Empty when the grantor is the owner.";
+                    };
+                };
+                readonly required: readonly ["manifest", "delegationTokens"];
+                readonly additionalProperties: false;
+            };
+        };
         readonly 'control/groupLeaveRequest': {
             readonly type: "event";
             readonly retain: "ephemeral";

package/lib/groups/group-protocols.js

@@ -395,6 +395,34 @@ import { defineGroupProtocol } from '@kumiai/rpc';
             additionalProperties: false
         }
     },
+    'control/credentialKeyManifest': {
+        type: 'event',
+        // Retained like the grant: an offline recipient must still find this on
+        // the epoch's app topic later, so it costs one log frame.
+        retain: 'log',
+        description: "A grantor's advisory record of the key set it granted a recipient (the readiness union). `manifest` is the grantor's signed token; `delegationTokens` proves its administer chain over the owner. Group-wide because the receiver keys the row on the manifest's own owner/recipient/grantor. The manifest authorizes nothing — the receiver's gate keeps a bogus one out of the store.",
+        data: {
+            type: 'object',
+            properties: {
+                manifest: {
+                    type: 'string',
+                    description: "The grantor's signed manifest token; its issuer is the authoritative grantor."
+                },
+                delegationTokens: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: "The grantor's administer-chain delegation tokens, closest-to-grantor first. Empty when the grantor is the owner."
+                }
+            },
+            required: [
+                'manifest',
+                'delegationTokens'
+            ],
+            additionalProperties: false
+        }
+    },
     'control/groupLeaveRequest': {
         type: 'event',
         retain: 'ephemeral',

package/lib/hub/wiring.d.ts

@@ -1,18 +1,22 @@
+import type { ClientTransportOf } from '@enkaku/protocol';
 import type { ProcedureHandlers } from '@enkaku/server';
 import type { OwnIdentity } from '@kokuin/token';
 import type { KubunDB } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { ServiceConfig, ServiceProtocol } from '@kubun/plugin-service-api';
 import type { LaneResult, PendingCommit } from '@kumiai/rpc';
 import type { Runtime } from '@sozai/runtime';
 import type { GroupBroadcastMessage } from '../groups/broadcast-message.js';
+import type { ControllerResolverFor } from '../groups/credential-wrapping-deps.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
 import type { BuildLedgerRedrive } from '../groups/group-peer-manager.js';
 import type { PeerPresence } from '../groups/peer-presence.js';
 import type { SyncProtocol } from '../protocol.js';
 import type { ForwardingConfig } from '../sync/forwarder.js';
+import type { ServeService } from '../sync/hub-tunnel-service-listener.js';
 import type { SyncTransportProvider } from '../sync/sync-client.js';
 import type { LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult, StoreUnreadableMode } from '../types.js';
 import type { CreateHubClient } from './http-client.js';
@@ -65,6 +69,12 @@ export type HubWiring = {
      * carries is authorized per document at the far end exactly as an HTTP one is.
      */
     syncTransportTo: (groupID: string, peerDID: string) => Promise<SyncTransportProvider | undefined>;
+    /**
+     * Build the transport for one directed SERVICE-lane session to a co-member,
+     * relayed by the group's hub — the mirror of {@link syncTransportTo} on the
+     * service lane. `undefined` when the group has no hub bound.
+     */
+    serviceTransportTo: (groupID: string, peerDID: string) => Promise<ClientTransportOf<ServiceProtocol> | undefined>;
     dispose: () => Promise<void>;
 };
 export type SetupHubRelayParams = {
@@ -113,6 +123,12 @@ export type SetupHubRelayParams = {
      * stamp is bounded there the same way the graph lane bounds a mutation's.
      */
     maxDriftMS: number;
+    /**
+     * The engine's `did:kokuin:` controller-resolver seam, forwarded to the apply
+     * path so a delegate-signed `credential:key-grant` wrapping can be authorized.
+     * Omitted, the delegated wrapping stays fail-closed.
+     */
+    controllerResolverFor?: ControllerResolverFor;
     /**
      * Reconnect-backoff overrides forwarded to every hub adapter. Test-only; when
      * omitted the adapter runs on its production defaults.
@@ -130,5 +146,13 @@ export type SetupHubRelayParams = {
      * answers none.
      */
     syncHandlers?: ProcedureHandlers<SyncProtocol>;
+    /**
+     * Injected `plugin-service-server` `serve()`, for answering an inbound
+     * service-lane tunnel session — see {@link ServeService}. Paired with
+     * `services`: both present is what serves the lane.
+     */
+    serviceServe?: ServeService;
+    /** Which services to serve on an inbound service-lane session. */
+    services?: Record<string, ServiceConfig>;
 };
 export declare function setupHubRelay(params: SetupHubRelayParams): HubWiring;

package/lib/hub/wiring.js

@@ -10,7 +10,7 @@ import { HubTunnelSyncProvider } from '../sync/hub-tunnel-sync-provider.js';
  * once per candidate before reporting `no-route`.
  */ const DEFAULT_TUNNEL_IDLE_TIMEOUT_MS = 30_000;
 export function setupHubRelay(params) {
-    const { identity, runtime, db, graph, emitter, createHubClient, registry, buildLedgerRedrive, logger, storeUnreadable, defaultAccessLevel, forwarding, hlc, maxDriftMS, hubReconnectBackoff, tunnelIdleTimeoutMs } = params;
+    const { identity, runtime, db, graph, emitter, createHubClient, registry, buildLedgerRedrive, logger, storeUnreadable, defaultAccessLevel, forwarding, hlc, maxDriftMS, controllerResolverFor, hubReconnectBackoff, tunnelIdleTimeoutMs } = params;
     const unsubscribes = [];
     // Late-bound `ready` resolving to the live manager. The fire-and-forget
     // schedulers chain off it so a caller can enqueue work before boot completes;
@@ -68,6 +68,10 @@ export function setupHubRelay(params) {
             logger: logger.getChild('tunnel-session')
         });
     };
+    const serviceTransportTo = async (groupID, peerDID)=>{
+        const provider = await (await ready).serviceTransportTo(groupID, peerDID);
+        return provider == null ? undefined : await provider.createServiceTransport();
+    };
     ready = (async ()=>{
         const [p2pStore, graphStore] = await Promise.all([
             db.getStore('p2p'),
@@ -90,6 +94,9 @@ export function setupHubRelay(params) {
             storeUnreadable,
             defaultAccessLevel,
             forwarding,
+            ...controllerResolverFor != null ? {
+                controllerResolverFor
+            } : {},
             // The manager's own fan-out, reached through the same late-bound `ready`
             // every other scheduler chains off — a forward is one more broadcast, so
             // it takes the path a locally-authored one already takes.
@@ -102,6 +109,14 @@ export function setupHubRelay(params) {
             ...params.syncHandlers != null ? {
                 syncHandlers: params.syncHandlers
             } : {},
+            // The service lane's answering half; both present is what serves it,
+            // either absent and no service listeners stand up.
+            ...params.serviceServe != null ? {
+                serviceServe: params.serviceServe
+            } : {},
+            ...params.services != null ? {
+                services: params.services
+            } : {},
             tunnelIdleTimeoutMs: tunnelIdleTimeoutMs ?? DEFAULT_TUNNEL_IDLE_TIMEOUT_MS
         });
         unsubscribes.push(emitter.on('groupJoined', (group)=>manager.addGroup(group.id).catch((error)=>{
@@ -170,6 +185,7 @@ export function setupHubRelay(params) {
         presence,
         retryHubs,
         syncTransportTo,
+        serviceTransportTo,
         dispose: async ()=>{
             for (const off of unsubscribes){
                 try {

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 import type { DefaultAccessLevel, KubunPlugin, PluginFactoryParams } from '@kubun/engine';
+import type { ServiceConfig } from '@kubun/plugin-service-api';
 import { type CreateHubClient } from './hub/http-client.js';
 import { type BroadcastBatchConfig } from './sync/broadcast-queue.js';
 import { type PushSyncConfig } from './sync/broadcast-sender.js';
@@ -172,5 +173,18 @@ export type P2PPluginOptions = {
      * which a headless test would otherwise have to wait out per offline peer.
      */
     tunnelIdleTimeoutMs?: number;
+    /**
+     * Serve service-lane sessions over the hub tunnel, on a distinct protocol
+     * from sync so ratchet generation is never shared. Requires the
+     * `service-server` plugin; `serviceTransportTo` still resolves for dialing
+     * out even when this device serves nothing.
+     * - `true` / `{}` — serve `{ 'controller-log': true }`.
+     * - `{ services }` — serve exactly this config (falls back to
+     *   `{ 'controller-log': true }` when `services` is omitted).
+     * - absent / `false` (default) — no service-lane listener.
+     */
+    serviceTunnel?: boolean | {
+        services?: Record<string, ServiceConfig>;
+    };
 };
 export declare function createP2PPlugin(options?: P2PPluginOptions): (params: PluginFactoryParams) => KubunPlugin;

package/lib/index.js

@@ -28,7 +28,9 @@ import { createP2PSchemaExtension } from './schema.js';
 import { wireAccessDefaultSender } from './sync/access-default-sender.js';
 import { createBroadcastQueue, DEFAULT_BROADCAST_BATCH_CONFIG } from './sync/broadcast-queue.js';
 import { DEFAULT_PUSH_SYNC_CONFIG, wireBroadcastSender } from './sync/broadcast-sender.js';
+import { createGroupSyncWorkflow, GROUP_SYNC_CONCURRENCY, GROUP_SYNC_WORKFLOW, wireGroupPeriodicSyncArming } from './sync/group-sync-workflow.js';
 import { createSyncHandlers } from './sync/handlers.js';
+import { ServiceServeNotReadyError, ServiceServeUnavailableError } from './sync/hub-tunnel-service-listener.js';
 import { SyncManager } from './sync/sync-manager.js';
 export { GROUP_CONTROL_DENIED, LAST_GROUP_ADMIN, NOT_GROUP_ADMIN, requireGroupAdmin } from './context/require-admin.js';
 export { ADMIN_ROLE_ENTRY_TYPE, foldAdminRoster } from './groups/admin-roster.js';
@@ -76,6 +78,26 @@ export { SyncManager } from './sync/sync-manager.js';
 function isOwnIdentity(identity) {
     return isFullIdentity(identity) && 'privateKey' in identity;
 }
+// Fixed 30s after a pass that pulled mutations; idle 2m→30m, offline 1m→30m,
+// error 30s→15m (both backing off exponentially). Group catch-up is a cheap
+// merkle diff, so the productive cadence is tighter than the connector's.
+const DEFAULT_GROUP_PERIODIC_SYNC_POLICY = {
+    changed: 30_000,
+    idle: {
+        base: 120_000,
+        max: 1_800_000
+    },
+    offline: {
+        base: 60_000,
+        max: 1_800_000,
+        backoff: 'exponential'
+    },
+    error: {
+        base: 30_000,
+        max: 900_000,
+        backoff: 'exponential'
+    }
+};
 export function createP2PPlugin(options) {
     return (params)=>{
         params.db.register(p2pStoreDefinition);
@@ -178,7 +200,7 @@ export function createP2PPlugin(options) {
             logger: params.getLogger('peer-connections')
         });
         // The p2p plugin manages its own Enkaku server for sync handlers,
-        // separate from plugin-rpc's graph server.
+        // separate from the graph service's server.
         const syncServers = [];
         function createSyncTransport(signal) {
             const directTransports = new DirectTransports({
@@ -222,6 +244,47 @@ export function createP2PPlugin(options) {
             fetch: params.runtime.fetch
         });
         const hubReconnectBackoff = typeof options?.hub === 'object' ? options.hub.reconnectBackoff : undefined;
+        // Which services (if any) this device answers on an inbound service-lane
+        // tunnel session; `undefined` means the service lane is not configured.
+        const serviceConfig = options?.serviceTunnel == null || options.serviceTunnel === false ? undefined : options.serviceTunnel === true ? {
+            'controller-log': true
+        } : options.serviceTunnel.services ?? {
+            'controller-log': true
+        };
+        // `getAPI` only resolves once every plugin factory has returned (see
+        // `Registry.closeGate` in `@kubun/engine`), so it can't be awaited here.
+        // `resolvedServe` fills in later, before any service session actually
+        // spawns (spawning waits on `setupHubRelay`'s internal `ready`, which
+        // resolves after every factory returns) — `serviceServe` below is thus a
+        // synchronous `ServeService` even though its target resolves lazily.
+        let resolvedServe;
+        // A permanent resolution failure (service-server not installed) must not
+        // read as transient "not ready" — that would retry a plugin that will
+        // never arrive. Track it so the wrapper throws the terminal error instead.
+        let serveResolutionFailed = false;
+        if (serviceConfig != null) {
+            void params.engine.getAPI('service-server').then((api)=>{
+                resolvedServe = api.serve;
+            }).catch((error)=>{
+                serveResolutionFailed = true;
+                hubRelayLogger.error('serviceTunnel is enabled but the "service-server" plugin API could not be resolved; the service lane will not serve', {
+                    error
+                });
+            });
+        }
+        const serviceServe = serviceConfig == null ? undefined : (serveParams)=>{
+            if (resolvedServe != null) {
+                return resolvedServe(serveParams);
+            }
+            // Terminal: the plugin API rejected and will not resolve. Stops the
+            // listener rather than letting it retry a plugin that never arrives.
+            if (serveResolutionFailed) {
+                throw new ServiceServeUnavailableError('serviceTunnel is enabled but the "service-server" plugin API could not be resolved');
+            }
+            // Transient: the API is still resolving (an early-spawn race). The
+            // listener retries on backoff and the next spawn finds it.
+            throw new ServiceServeNotReadyError('serviceTunnel is enabled but the "service-server" plugin API is not ready yet');
+        };
         const hub = setupHubRelay({
             identity,
             runtime: params.runtime,
@@ -243,6 +306,10 @@ export function createP2PPlugin(options) {
             storeUnreadable: receiveConfig.storeUnreadable,
             defaultAccessLevel,
             forwarding: options?.forwarding,
+            // The engine's controller-resolver seam, so a delegate-signed
+            // `credential:key-grant` wrapping received over the live broadcast lane can
+            // be authorized against the grantor's administer chain.
+            controllerResolverFor: params.controllerResolverFor,
             ...hubReconnectBackoff != null ? {
                 hubReconnectBackoff
             } : {},
@@ -251,7 +318,13 @@ export function createP2PPlugin(options) {
             } : {},
             // The same handlers the direct and HTTP transports serve — a tunnel is a
             // route, so it must not reach a different sync implementation.
-            syncHandlers: syncHandlers
+            syncHandlers: syncHandlers,
+            // The service lane's answering half; absent, `setupHubRelay` stands up
+            // no service listeners, so a device without `serviceTunnel` is unchanged.
+            ...serviceServe != null ? {
+                serviceServe,
+                services: serviceConfig
+            } : {}
         });
         // 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
@@ -329,6 +402,9 @@ export function createP2PPlugin(options) {
                 adapter,
                 hlc,
                 maxDriftMS: params.maxDriftMS,
+                // The engine's controller-resolver seam, so the credential reconcile-apply
+                // lane (catch-up) can authorize a delegate-signed wrapping it pulls back.
+                controllerResolverFor: params.controllerResolverFor,
                 emitter,
                 runtime: params.runtime,
                 autoAcceptPeers: options?.autoAcceptPeers,
@@ -390,8 +466,74 @@ export function createP2PPlugin(options) {
             logger: params.getLogger('controller-handlers'),
             autoAcceptPeers: options?.autoAcceptPeers
         });
+        // Recurring group catch-up over the workflow engine's adaptive scheduler. One
+        // `catchUpWithBestPeer` pass is one durable tick, run viewer-independent through
+        // the SAME sync context the GraphQL surface and the API use, so a scheduled
+        // catch-up cannot ask for scopes an explicit one would not.
+        const groupSyncWorkflow = createGroupSyncWorkflow({
+            catchUpWithBestPeer: (groupID)=>createSyncContext(null, buildContextDeps(params.db)).catchUpWithBestPeer(groupID),
+            logger: params.getLogger('group-sync')
+        });
+        let workflowAPIPromise;
+        const getWorkflowAPI = ()=>{
+            if (workflowAPIPromise == null) {
+                workflowAPIPromise = params.engine.getAPI('workflow').then((api)=>{
+                    api.defineQueue(GROUP_SYNC_WORKFLOW, {
+                        concurrency: GROUP_SYNC_CONCURRENCY
+                    });
+                    api.register(groupSyncWorkflow.definition);
+                    return api;
+                }).catch(()=>undefined);
+            }
+            return workflowAPIPromise;
+        };
+        // Resolve once at boot so the definition + queue register before any due
+        // schedule fires: an implicit schedule armed on a prior run is promoted by the
+        // engine at startup and needs its handler present, which the connector's
+        // lazy-only resolve does not have to guarantee (nothing schedules it implicitly).
+        void getWorkflowAPI();
+        // Implicit activation: arm a schedule the first time a group is joined,
+        // insert-if-absent (see `wireGroupPeriodicSyncArming`).
+        wireGroupPeriodicSyncArming({
+            emitter,
+            getWorkflowAPI,
+            policy: DEFAULT_GROUP_PERIODIC_SYNC_POLICY,
+            logger: params.getLogger('group-sync')
+        });
+        // Explicit control. `enable` always (re)activates — the deliberate opposite of
+        // the implicit insert-if-absent guard — so the user turning it back on wins.
+        const groupPeriodicSyncControl = {
+            enableGroupPeriodicSync: async (groupID, policyOverride)=>{
+                const api = await getWorkflowAPI();
+                if (api == null) {
+                    throw new Error('workflow plugin required for periodic sync');
+                }
+                const { id } = await api.scheduleAdaptive(GROUP_SYNC_WORKFLOW, {
+                    groupID
+                }, {
+                    policy: policyOverride ?? DEFAULT_GROUP_PERIODIC_SYNC_POLICY,
+                    subjectKey: groupID
+                });
+                return api.getPeriodicSync(id);
+            },
+            disableGroupPeriodicSync: async (groupID)=>{
+                const api = await getWorkflowAPI();
+                if (api == null) {
+                    throw new Error('workflow plugin required for periodic sync');
+                }
+                return api.setPeriodicSyncEnabled(`${GROUP_SYNC_WORKFLOW}:${groupID}`, false);
+            },
+            getGroupPeriodicSync: async (groupID)=>{
+                const api = await getWorkflowAPI();
+                if (api == null) {
+                    throw new Error('workflow plugin required for periodic sync');
+                }
+                return api.getPeriodicSync(`${GROUP_SYNC_WORKFLOW}:${groupID}`);
+            }
+        };
         const pluginAPI = {
             hubReady: hub.ready,
+            ...groupPeriodicSyncControl,
             addPeer: (config)=>syncManager.addPeer({
                     config,
                     stores: params.db
@@ -420,6 +562,7 @@ export function createP2PPlugin(options) {
             onHubServerDIDChanged: (listener)=>emitter.on('hubServerDIDChanged', listener),
             createSyncTransport,
             requestLedgerCatchup: (groupID, options)=>hub.requestLedgerCatchup(groupID, options),
+            serviceTransportTo: (groupID, peerDID)=>hub.serviceTransportTo(groupID, peerDID),
             setLocalPeerProfile: async (profile)=>{
                 await (await hub.presence()).setProfile(profile);
             },
@@ -432,11 +575,19 @@ export function createP2PPlugin(options) {
                     peerConnections,
                     getBlobAPI: ()=>params.engine.getAPI('blob'),
                     fetch: params.runtime.fetch
-                }, attachmentID, options),
-            fetchControllerLog: (did)=>fetchControllerLog({
+                }, attachmentID, options)
+        };
+        // The controller resolver pulls a `did:kokuin:` log over `controller/get-log`
+        // from a connected group peer on a store miss/expiry. Registered as a
+        // `networked` provider (the engine times it out and folds the result) rather
+        // than an API member the engine reached by string.
+        params.registerProvider('controller-log-source', {
+            name: 'p2p',
+            transport: 'networked',
+            fetch: (did)=>fetchControllerLog({
                     peerConnections
                 }, did)
-        };
+        });
         let httpSyncTransport;
         let httpSyncServer;
         let httpPeerTransport;
@@ -528,7 +679,7 @@ export function createP2PPlugin(options) {
         }
         return {
             name: 'p2p',
-            schemaExtension: (_config)=>createP2PSchemaExtension(emitter, syncManager, params.getLogger('p2p-schema')),
+            schemaExtension: (config)=>createP2PSchemaExtension(emitter, syncManager, params.getLogger('p2p-schema'), groupPeriodicSyncControl, config),
             api: pluginAPI,
             createContextFactory: ()=>{
                 return (ctx, stores)=>{