@kubun/plugin-p2p 0.14.0 → 0.15.0

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

@@ -0,0 +1,100 @@
+import { createEncryptedHubTunnelTransport } from '@kumiai/hub-tunnel';
+import { APP_TOPIC_LABEL } from '@kumiai/rpc';
+import { createGroupCrypto } from '../groups/group-crypto.js';
+import { MLSEncryptor } from '../groups/mls-encryptor.js';
+import { createSenderScopedHubView } from '../hub/sender-scoped-hub-view.js';
+import { SERVICE_TUNNEL_PROTOCOL, tunnelTopic } from './tunnel-topics.js';
+/**
+ * Dial side of the SERVICE tunnel — the same directed hub-tunnel machinery as
+ * {@link HubTunnelSyncProvider}, riding a distinct lane so a service session to
+ * a peer never collides with a sync session's topics or ratchet generation.
+ */ export class HubTunnelServiceProvider {
+    #hub;
+    #registry;
+    #groupID;
+    #localDID;
+    #peerDID;
+    #runtime;
+    #idleTimeoutMs;
+    #logger;
+    constructor(params){
+        this.#hub = params.hub;
+        this.#registry = params.registry;
+        this.#groupID = params.groupID;
+        this.#localDID = params.localDID;
+        this.#peerDID = params.peerDID;
+        this.#runtime = params.runtime;
+        this.#idleTimeoutMs = params.idleTimeoutMs;
+        this.#logger = params.logger;
+    }
+    /**
+   * Build a fresh client transport for one tunnel service session.
+   *
+   * Topics are group- and role-scoped, derived from the current MLS epoch
+   * secret on the service lane: outbound frames publish to the peer's
+   * responder topic, and the transport subscribes to this device's own dialer
+   * topic. Topics rotate with the epoch, so callers create a new transport per
+   * session.
+   */ async createServiceTransport(signal) {
+        const sessionID = this.#runtime.getRandomID();
+        const encryptor = new MLSEncryptor({
+            registry: this.#registry,
+            groupID: this.#groupID
+        });
+        // The seed epoch is unread here: this port never classifies commit frames,
+        // and `exportSecret()` below records the live epoch before `epoch()` is
+        // asked for it. Only a peer that opens a receive drain needs a real seed.
+        const crypto = createGroupCrypto({
+            registry: this.#registry,
+            groupID: this.#groupID,
+            initialEpoch: 0,
+            runtime: this.#runtime
+        });
+        const secret = await crypto.exportSecret(APP_TOPIC_LABEL);
+        const epoch = crypto.epoch();
+        // SERVICE lane — the only substantive difference from the sync provider.
+        const sendTopicID = tunnelTopic(secret, epoch, 'responder', this.#peerDID, SERVICE_TUNNEL_PROTOCOL);
+        const receiveTopicID = tunnelTopic(secret, epoch, 'dialer', this.#localDID, SERVICE_TUNNEL_PROTOCOL);
+        // Bound once and carried by every line this session logs — the transport's
+        // own idle timeout raises a bare `TimeoutInterruption` with none of this
+        // context.
+        const sessionLogger = this.#logger?.with({
+            role: 'dialer',
+            lane: 'service',
+            groupID: this.#groupID,
+            peerDID: this.#peerDID,
+            sessionID,
+            epoch,
+            receiveTopicID
+        });
+        sessionLogger?.debug('tunnel session opening');
+        const transport = createEncryptedHubTunnelTransport({
+            // The peer-scoped view, never the device hub: two sessions open at once
+            // share the same inbox topic, and MLS consumes a ratchet generation per
+            // open, destroying the frame for whichever session loses the race.
+            // The idle timeout doubles as the publish bound so "no receive" and "no
+            // send" give up on the same promise rather than drifting apart.
+            hub: createSenderScopedHubView({
+                hub: this.#hub,
+                peerDID: this.#peerDID,
+                ...this.#idleTimeoutMs == null ? {} : {
+                    publishTimeoutMs: this.#idleTimeoutMs
+                }
+            }),
+            encryptor,
+            groupID: this.#groupID,
+            sessionID,
+            localDID: this.#localDID,
+            sendTopicID,
+            receiveTopicID,
+            signal,
+            idleTimeoutMs: this.#idleTimeoutMs
+        });
+        // Close is as load-bearing as open: an unreachable peer looks like a
+        // session ending without having received anything.
+        transport.events.on('disposed', ()=>{
+            sessionLogger?.debug('tunnel session closed');
+        });
+        return transport;
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { OwnIdentity } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { ServiceConfig } from '@kubun/plugin-service-api';
+import type { MailboxHub } from '@kumiai/hub-tunnel';
+import type { Runtime } from '@sozai/runtime';
+import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import { type ServeService } from './hub-tunnel-service-listener.js';
+import type { TunnelListeners } from './tunnel-listeners.js';
+export type ServiceTunnelListenersParams = {
+    stores: StoreProvider;
+    registry: GroupHandleRegistry;
+    identity: OwnIdentity;
+    localDID: string;
+    runtime: Runtime;
+    /** Injected `plugin-service-server` `serve()` — see {@link ServeService}. */
+    serve: ServeService;
+    /** Which services to serve, forwarded verbatim to `serve` on every spawn. */
+    services: Record<string, ServiceConfig>;
+    /** The group's device-wide drain, or `undefined` when no hub is bound. */
+    tunnelHub: (groupID: string) => MailboxHub | undefined;
+    logger?: Logger;
+    idleTimeoutMs?: number;
+};
+/**
+ * The answering half of the service tunnel — one `HubTunnelServiceListener` per
+ * co-member per group, so a device dialing on the service lane finds something
+ * draining the mailbox and handing the session to the injected `serve()`.
+ *
+ * Structurally identical to {@link createTunnelListeners} (the sync lane's
+ * answering half): same groupID→peerDID map, same epoch/hub-change teardown,
+ * same per-group serialized reconciles — only the listener class and what's
+ * threaded into it differ, so the two lanes never share an instance or ratchet.
+ */
+export declare function createServiceTunnelListeners(params: ServiceTunnelListenersParams): TunnelListeners;

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

@@ -0,0 +1,165 @@
+import { normalizeDID } from '@kokuin/token';
+import { getP2PStore } from '@kubun/store-p2p';
+import { HubTunnelServiceListener } from './hub-tunnel-service-listener.js';
+/**
+ * The answering half of the service tunnel — one `HubTunnelServiceListener` per
+ * co-member per group, so a device dialing on the service lane finds something
+ * draining the mailbox and handing the session to the injected `serve()`.
+ *
+ * Structurally identical to {@link createTunnelListeners} (the sync lane's
+ * answering half): same groupID→peerDID map, same epoch/hub-change teardown,
+ * same per-group serialized reconciles — only the listener class and what's
+ * threaded into it differ, so the two lanes never share an instance or ratchet.
+ */ export function createServiceTunnelListeners(params) {
+    const selfDID = normalizeDID(params.localDID);
+    const { logger } = params;
+    // groupID → peerDID → its listener.
+    const listeners = new Map();
+    // Which drain each group's listeners were built on. A listener holds its hub
+    // for life, so a group that switches hubs needs new ones — and the peer set
+    // alone cannot show that, since the same members are still wanted.
+    const attachedHubs = new Map();
+    // And which epoch they derived their topics at. A live listener's subscription
+    // is pinned to its spawn epoch; only a disposed transport re-derives, so a
+    // group whose epoch moved would otherwise keep draining a stale topic.
+    const attachedEpochs = new Map();
+    // Reconciles of one group run in sequence: an epoch burst fires several, and
+    // two interleaved passes over the same map would each start a listener the
+    // other has not recorded yet.
+    const queues = new Map();
+    let disposed = false;
+    const stopGroup = async (groupID)=>{
+        attachedHubs.delete(groupID);
+        attachedEpochs.delete(groupID);
+        const group = listeners.get(groupID);
+        if (group == null) {
+            return;
+        }
+        listeners.delete(groupID);
+        await Promise.allSettled([
+            ...group.values()
+        ].map((listener)=>listener.stop()));
+    };
+    const runReconcile = async (groupID)=>{
+        if (disposed) {
+            return;
+        }
+        const store = await getP2PStore(params.stores);
+        const profile = await store.getLocalPeerProfile(selfDID);
+        if (profile == null) {
+            await stopGroup(groupID);
+            return;
+        }
+        const hub = params.tunnelHub(groupID);
+        if (hub == null) {
+            // No hub bound: there is no mailbox to drain. A binding arriving later
+            // reconciles again.
+            await stopGroup(groupID);
+            return;
+        }
+        const epoch = params.registry.groupEpoch(groupID);
+        if (attachedHubs.get(groupID) !== hub || attachedEpochs.get(groupID) !== epoch) {
+            await stopGroup(groupID);
+        }
+        attachedHubs.set(groupID, hub);
+        attachedEpochs.set(groupID, epoch);
+        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);
+        if (group == null) {
+            group = new Map();
+            listeners.set(groupID, group);
+        }
+        for (const [peerDID, listener] of group){
+            if (!wanted.has(peerDID)) {
+                group.delete(peerDID);
+                try {
+                    await listener.stop();
+                } catch (error) {
+                    logger?.warn('service tunnel listener stop failed', {
+                        groupID,
+                        peerDID,
+                        error
+                    });
+                }
+            }
+        }
+        // Every await above is a point where the group could have been left or the
+        // whole thing disposed. A pass that continued past one would repopulate
+        // `listeners` with fresh, STARTED listeners for a group this device is no
+        // longer in, and they would drain that group's inbox topic indefinitely —
+        // nothing later removes what `removeGroup` already walked past.
+        if (disposed || listeners.get(groupID) !== group) {
+            return;
+        }
+        for (const peerDID of wanted){
+            if (group.has(peerDID)) {
+                continue;
+            }
+            const listener = new HubTunnelServiceListener({
+                hub,
+                registry: params.registry,
+                groupID,
+                localDID: selfDID,
+                peerDID,
+                runtime: params.runtime,
+                serve: params.serve,
+                services: params.services,
+                ...params.idleTimeoutMs != null ? {
+                    idleTimeoutMs: params.idleTimeoutMs
+                } : {},
+                ...logger != null ? {
+                    logger
+                } : {}
+            });
+            group.set(peerDID, listener);
+            listener.start();
+        }
+    };
+    const reconcile = (groupID)=>{
+        const queued = (queues.get(groupID) ?? Promise.resolve()).then(()=>runReconcile(groupID), ()=>runReconcile(groupID));
+        // Never let one group's failure reject a caller that only asked for a
+        // reconcile — the next signal retries, and a throw here would surface on
+        // whichever unrelated lane happened to trigger it.
+        const settled = queued.catch((error)=>{
+            logger?.warn('service tunnel listener reconcile failed', {
+                groupID,
+                error
+            });
+        });
+        queues.set(groupID, settled);
+        return settled;
+    };
+    return {
+        reconcile,
+        reconcileAll: async (groupIDs)=>{
+            await Promise.all(groupIDs.map((groupID)=>reconcile(groupID)));
+        },
+        removeGroup: async (groupID)=>{
+            // Await the in-flight reconcile BEFORE tearing down. Dropping the queue
+            // entry does not stop the pass already running: it would finish after the
+            // stop and leave started listeners behind for a group the device has
+            // left. `runReconcile` also re-checks, so this is the pair.
+            const queued = queues.get(groupID);
+            queues.delete(groupID);
+            if (queued != null) {
+                await queued.catch(()=>{
+                // A failed reconcile is already logged; the teardown proceeds.
+                });
+            }
+            await stopGroup(groupID);
+        },
+        dispose: async ()=>{
+            disposed = true;
+            const inFlight = [
+                ...queues.values()
+            ];
+            queues.clear();
+            await Promise.allSettled(inFlight);
+            const groupIDs = [
+                ...listeners.keys()
+            ];
+            await Promise.allSettled(groupIDs.map((groupID)=>stopGroup(groupID)));
+        }
+    };
+}

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

@@ -64,6 +64,13 @@ export type MerkleSyncParams = {
      * is swallowed — the credential lane must never fail the doc sync.
      */
     reconcileCredentialsHeld?: SyncReconcileCredentialsParam['held'];
+    /**
+     * Owner DIDs to pull the latest durable manifest for, addressed to this
+     * device, alongside the same `sync/reconcile-credentials` request — the PULL
+     * repair channel independent of LIVE broadcast. Undefined omits `owners`
+     * from the wire request entirely, leaving existing behavior unchanged.
+     */
+    reconcileCredentialOwners?: Array<string>;
 };
 export declare class SyncManager {
     #private;

package/lib/sync/sync-manager.js

@@ -136,7 +136,10 @@ export class SyncManager {
                 try {
                     credentialReconcile = await client.request('sync/reconcile-credentials', {
                         param: {
-                            held: params.reconcileCredentialsHeld
+                            held: params.reconcileCredentialsHeld,
+                            ...params.reconcileCredentialOwners != null && {
+                                owners: params.reconcileCredentialOwners
+                            }
                         }
                     });
                 } catch (error) {

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

@@ -1,3 +1,21 @@
+/**
+ * The lane every directed sync tunnel rides, owned by this package.
+ *
+ * Deliberately not `inboxTopic`: that derives ONE topic per member, so a device
+ * dialing a peer and answering that same peer both read and both write the two
+ * members' inboxes. The two roles then share a topic, and sender scope cannot
+ * separate them — a peer's reply and that peer's own dial request are equally
+ * "from the peer". Whichever of the two opens a frame first consumes its MLS
+ * ratchet generation and DESTROYS it for the other, which waits out its idle
+ * timeout instead. `inboxTopic` is also `@kumiai/rpc`'s reserved lane, and a
+ * host protocol has no business publishing into it.
+ */
+export declare const SYNC_TUNNEL_PROTOCOL = "kubun/sync-tunnel/v1";
+/**
+ * Distinct protocol label so a service session never shares a ratchet
+ * generation with a sync session to the same peer.
+ */
+export declare const SERVICE_TUNNEL_PROTOCOL = "kubun/service-tunnel/v1";
 /**
  * Which side of a directed session a topic belongs to. A `dialer` topic carries
  * the responses flowing back to whoever opened the session; a `responder` topic
@@ -17,4 +35,4 @@ export type TunnelRole = 'dialer' | 'responder';
  * nothing in the sync client opens those, and a session id in the scope would
  * cost a round trip to agree on before either side could subscribe.
  */
-export declare function tunnelTopic(secret: Uint8Array, epoch: number, role: TunnelRole, ownerDID: string): string;
+export declare function tunnelTopic(secret: Uint8Array, epoch: number, role: TunnelRole, ownerDID: string, protocol?: string): string;

package/lib/sync/tunnel-topics.js

@@ -10,7 +10,11 @@ import { protocolTopic } from '@kumiai/rpc';
  * ratchet generation and DESTROYS it for the other, which waits out its idle
  * timeout instead. `inboxTopic` is also `@kumiai/rpc`'s reserved lane, and a
  * host protocol has no business publishing into it.
- */ const SYNC_TUNNEL_PROTOCOL = 'kubun/sync-tunnel/v1';
+ */ export const SYNC_TUNNEL_PROTOCOL = 'kubun/sync-tunnel/v1';
+/**
+ * Distinct protocol label so a service session never shares a ratchet
+ * generation with a sync session to the same peer.
+ */ export const SERVICE_TUNNEL_PROTOCOL = 'kubun/service-tunnel/v1';
 /**
  * The topic on which `ownerDID` receives the frames addressed to it in `role`.
  *
@@ -23,6 +27,6 @@ import { protocolTopic } from '@kumiai/rpc';
  * Two sessions in the same role to the SAME peer at once would still contend —
  * nothing in the sync client opens those, and a session id in the scope would
  * cost a round trip to agree on before either side could subscribe.
- */ export function tunnelTopic(secret, epoch, role, ownerDID) {
-    return protocolTopic(secret, epoch, SYNC_TUNNEL_PROTOCOL, `${role}:${ownerDID}`);
+ */ export function tunnelTopic(secret, epoch, role, ownerDID, protocol = SYNC_TUNNEL_PROTOCOL) {
+    return protocolTopic(secret, epoch, protocol, `${role}:${ownerDID}`);
 }

package/lib/types.d.ts

@@ -1,7 +1,9 @@
 import type { ClientTransportOf } from '@enkaku/protocol';
+import type { ServiceProtocol } from '@kubun/plugin-service-api';
 import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
 import type { AccessLevel } from '@kubun/store-graph';
 import type { ControlRequestKind, ControlRequestOutcome } from '@kubun/store-p2p';
+import type { CredentialGrantOutcomeKind } from './groups/credential-grant.js';
 import type { PeerAvailability, PeerCapability } from './groups/group-protocols.js';
 import type { PeerConnection } from './peer/connection-registry.js';
 import type { SyncDirection, SyncProtocol } from './protocol.js';
@@ -392,6 +394,17 @@ export type SyncPeerData = {
     messagesReceived: number;
     messagesSent: number;
     divergentBuckets: number;
+    /**
+     * Rows the piggybacked credential reconcile moved in: manifests stored,
+     * bundles applied, rows tombstoned. Absent both when the lane never ran and
+     * when its apply failed (swallowed to keep doc catch-up non-fatal) — not a
+     * completeness signal; use the manifest-vs-store readiness query for that.
+     */
+    credentialReconcileApplied?: {
+        manifestsApplied: number;
+        applied: number;
+        tombstoned: number;
+    };
 };
 /**
  * Why an automatic catch-up carried nothing — the distinction all-zero counts
@@ -549,6 +562,12 @@ export type AdmitJoinRequestParams = {
      * payload's own `did` field is only cross-checked against it.
      */
     joinRequest: string;
+    /**
+     * Delegation tokens delivered to the joiner atomically with admission (e.g.
+     * a controller→device grant), via the same InvitePayload.grants path as
+     * `requestInvite`.
+     */
+    grants?: Array<string>;
     /** See {@link SharePeerGroupParams.sendModels}. */
     sendModels?: Array<string> | null;
     /** See {@link SharePeerGroupParams.receiveActivate}. */
@@ -570,6 +589,110 @@ export type JoinPeerGroupParams = {
     /** The group to join, as discovered from the peer's `connectPeer` group list. */
     groupID: string;
 };
+export type GrantDeviceCredentialsParams = {
+    /**
+     * The MLS group whose roster `recipientDID` must resolve in — the same
+     * lookup `grantCredentialKeyToMember` makes to find a wrappable form.
+     */
+    groupID: string;
+    /** The device being granted this batch of `ownerDID`'s active credential keys. */
+    recipientDID: string;
+    /**
+     * The credential owner whose active keys are enumerated and granted.
+     * Normalized once and reused for the grant calls and the manifest so both
+     * name the same principal.
+     */
+    ownerDID: string;
+    /**
+     * Floor for the allocated provisioning epoch (`nextProvisioningEpoch` =
+     * `max(stored, minEpoch) + 1`); defaults to 0. Pass a recipient's known
+     * held epoch to force the new manifest strictly past it.
+     */
+    minEpoch?: number;
+};
+/**
+ * One key's outcome from a `grantDeviceCredentials` batch — never thrown; the
+ * batch reports every key's fate so a caller can retry only what didn't land.
+ */
+export type CredentialGrantOutcome = {
+    keyID: string;
+    /** The key's version after this call, or `null` for `not-held`/`error` outcomes. */
+    version: number | null;
+    outcome: CredentialGrantOutcomeKind;
+    /** Present on `not-held` and `error`; the caught error's message. */
+    reason?: string;
+};
+export type CredentialProvisioningStatusParams = {
+    /**
+     * The credential owner whose per-grantor manifests addressed to THIS device
+     * name the keys expected here. Normalized once alongside the viewer.
+     */
+    ownerDID: string;
+};
+export type CredentialProvisioningStatusData = {
+    /** True iff every durable expectation is satisfied — `missing` is empty. */
+    complete: boolean;
+    /**
+     * Expected keyIDs not yet materialized here: absent, unwrapped for this
+     * device, or locked behind a wrapping that never decrypt-verifies.
+     */
+    missing: Array<string>;
+    /**
+     * Explains a `false` verdict: `'not-initiated'` (no expectations recorded
+     * yet), `'pending'` (an attempt in flight, floor not bound), or
+     * `'incomplete'` (recorded but not yet satisfied). Absent when `complete`.
+     */
+    reason?: 'not-initiated' | 'pending' | 'incomplete';
+};
+export type BeginProvisioningExpectationParams = {
+    /** The credential owner this expectation tracks provisioning for. */
+    ownerDID: string;
+    /** The grantor this device expects a manifest from. */
+    grantorDID: string;
+};
+export type BeginProvisioningExpectationData = {
+    /** Freshly minted attempt id; pass it to `recordProvisioningExpectation`/`abandonProvisioningExpectation`. */
+    attemptId: string;
+};
+export type RecordProvisioningExpectationParams = {
+    ownerDID: string;
+    grantorDID: string;
+    /** The id `beginProvisioningExpectation` minted for this attempt. */
+    attemptId: string;
+    /** The epoch this attempt's grant call was allocated and signed under. */
+    epoch: number;
+};
+export type RecordProvisioningExpectationData = {
+    status: 'recorded';
+} | {
+    status: 'retry';
+    /** The recipient's now-held epoch; re-run the grant with this as the new `minEpoch`. */
+    minEpoch: number;
+};
+export type AbandonProvisioningExpectationParams = {
+    ownerDID: string;
+    grantorDID: string;
+    /** The id to stop tracking. Removes ONLY this id; never binds or lowers a floor. */
+    attemptId: string;
+};
+export type ProvisioningHeldEpochParams = {
+    ownerDID: string;
+    grantorDID: string;
+};
+export type GrantDeviceCredentialsData = {
+    /** One entry per active key `ownerDID` holds on this device, in listed order. */
+    results: Array<CredentialGrantOutcome>;
+    /**
+     * A grantor-signed manifest claiming the structural target — every active
+     * key this grantor can itself distribute (`store.listDistributableKeys`) —
+     * independent of which of those this particular call's per-key grants
+     * actually succeeded on. The recipient checks its store against it to prove
+     * it holds the whole set, not just what one batch call happened to land.
+     */
+    manifest: string;
+    /** The provisioning epoch this manifest was allocated and signed under. */
+    epoch: number;
+};
 /** The read access-rule fields a `setCircleSync` add/remove writes for a model. */
 export type SetReadDefaultParams = {
     modelID: string;
@@ -718,6 +841,47 @@ export type PeerRequestContext = {
      * the admin opened or closed since the join.
      */
     listCircleSyncStates: (groupID: string) => Promise<Array<CircleSyncStateData>>;
+    /**
+     * Grant every one of `ownerDID`'s active credential keys to `recipientDID` in
+     * one non-throwing batch (each key's failure is its own outcome, never
+     * aborting the rest), then return a grantor-signed manifest over what landed.
+     */
+    grantDeviceCredentials: (params: GrantDeviceCredentialsParams) => Promise<GrantDeviceCredentialsData>;
+    /**
+     * Prove this device holds the complete expected credential set for
+     * `ownerDID` — the union of keys named across every per-grantor manifest.
+     * A key counts materialized only when its wrapping decrypt-verifies (or,
+     * for a zero-entry key, is merely openable); presence and a valid
+     * signature chain alone are not enough.
+     */
+    credentialProvisioningStatus: (params: CredentialProvisioningStatusParams) => Promise<CredentialProvisioningStatusData>;
+    /**
+     * Begin tracking a provisioning attempt for `(ownerDID, grantorDID)`: mints
+     * an `attemptId` and forces `credentialProvisioningStatus` to `pending`
+     * until recorded/abandoned. Call BEFORE asking the grantor to grant, to
+     * close the epoch-allocation race window.
+     */
+    beginProvisioningExpectation: (params: BeginProvisioningExpectationParams) => Promise<BeginProvisioningExpectationData>;
+    /**
+     * Record the outcome of a provisioning attempt via an atomic
+     * compare-and-record against this device's currently-held epoch. If the
+     * attempt's epoch still exceeds it, the floor advances (`'recorded'`);
+     * otherwise a higher manifest already arrived and the attempt stays
+     * outstanding (`'retry'`, `minEpoch`) — retry the grant and call again with
+     * the same `attemptId`.
+     */
+    recordProvisioningExpectation: (params: RecordProvisioningExpectationParams) => Promise<RecordProvisioningExpectationData>;
+    /**
+     * Stop tracking a dead/abandoned provisioning attempt: removes only this
+     * `attemptId` from the outstanding set, never touches the epoch floor.
+     */
+    abandonProvisioningExpectation: (params: AbandonProvisioningExpectationParams) => Promise<void>;
+    /**
+     * This device's currently-held epoch for `(ownerDID, grantorDID)` — max
+     * epoch among held manifests from that grantor, or `0`. Feeds `minEpoch`
+     * for `grantDeviceCredentials` so a new attempt's epoch exceeds it.
+     */
+    provisioningHeldEpoch: (params: ProvisioningHeldEpochParams) => Promise<number>;
 };
 export type P2PJoinRequestContext = {
     prepareRequest: () => Promise<{
@@ -968,6 +1132,14 @@ export type SyncPluginAPI = {
      * no-op (all-zero summary) when no `hub` option is configured.
      */
     requestLedgerCatchup(groupID: string, options?: LedgerCatchupOptions): Promise<LedgerCatchupSummary>;
+    /**
+     * Build the transport for one directed service-lane session to a
+     * co-member, relayed by the group's hub — the service-lane mirror of the
+     * sync tunnel's route resolver. `undefined` when the group has no hub
+     * bound. A route only: it grants no access to what the far end serves;
+     * that's decided by the far end's own `serviceTunnel` config.
+     */
+    serviceTransportTo(groupID: string, peerDID: string): Promise<ClientTransportOf<ServiceProtocol> | undefined>;
     /**
      * Declare what this device IS — its display label, its availability class and
      * the capabilities it answers — and advertise it to every group it belongs to.