@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/sync/sync-client.js

@@ -1 +1,192 @@
-import{Client as e}from"@enkaku/client";import{ClientTransport as t}from"@enkaku/http-client-transport";import{findDivergentBuckets as r,getTimeBuckets as n,SYNC_BATCH_SIZE as i}from"./merkle-tree.js";export class SyncClient{#e;#t;#r;#n;constructor(e){this.#e=e.runtime,this.#t=e.identity,this.#r=e.logger,this.#n=e.serverResolver}async connect(e,t){if(e.startsWith("direct://"))return this.#i(e);if(e.startsWith("http://")||e.startsWith("https://"))return this.#s(e,t);throw Error(`Unsupported endpoint scheme: ${e}`)}#s(r,n){let i=new t({url:r,fetch:this.#e.fetch});return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:n,transport:i})}#i(t){let r=t.replace("direct://","");if(!this.#n)throw Error("Server resolver not configured for direct transport");let n=this.#n(r);if(!n)throw Error(`Server not found: ${r}`);let i=n.createSyncTransport();return new e({runtime:this.#e,identity:this.#t,logger:this.#r.getChild("sync-client"),serverID:r,transport:i})}async negotiate(e,t,r=[],n,i){this.#r.debug("Negotiate: sending {scopeCount} scopes",{scopeCount:t.length});let s=await e.request("sync/negotiate",{param:{scopes:t,delegationTokens:r,knownModelIDs:n,direction:i}});return this.#r.debug("Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs",{acceptedCount:s.acceptedScopes.length,excludedCount:s.excludedDocumentIDs.length}),s}async merkleSync(e,t){let{scopes:s,excludedDocumentIDs:o,localTree:c,direction:l,localEntries:a}=t;this.#r.debug("MerkleSync: creating channel with {buckets} local buckets",{buckets:Object.keys(c.buckets).length});let u=e.createChannel("sync/merkle-sync",{param:{scopes:s,excludedDocumentIDs:o,tree:c.buckets,direction:l}}),h=u.readable.getReader(),d=await h.read();if(d.done)throw Error("MerkleSync: channel closed before receiving remote tree");let g=d.value;if("tree"!==g.type)throw Error(`MerkleSync: expected 'tree' message, got '${g.type}'`);let p=r(c,{root:g.tree?.root??"",buckets:g.tree??{}}),m=p.length;this.#r.debug("MerkleSync: found {count} divergent buckets",{count:m});let y=0,f=async()=>{if("push"===l||"both"===l){let e=new Set(p),t=a.filter(t=>{let{minute:r}=n(t.hlc);return e.has(r)});for(let e=0;e<t.length;e+=i){let r=t.slice(e,e+i);await u.send({type:"mutations",mutationJWTs:r.map(e=>e.mutation_jwt)}),y+=r.length}}await u.send({type:"complete"})},k=async()=>{let e=[];for(;;){let{done:t,value:r}=await h.read();if(t)break;if("mutations"===r.type&&null!=r.mutationJWTs)e.push(...r.mutationJWTs);else if("complete"===r.type)break}return h.releaseLock(),e},[,v]=await Promise.all([f(),k()]),w=await u;if(null!=w&&!w.success)throw Error("MerkleSync: responder reported failure");return this.#r.debug("MerkleSync: completed with {received} received, {sent} sent",{received:v.length,sent:y}),{mutationJWTs:v,divergentBuckets:m,mutationsSent:y}}}
+import { Client } from '@enkaku/client';
+import { ClientTransport as HTTPClientTransport } from '@enkaku/http-fetch';
+import { findDivergentBuckets, getTimeBuckets, SYNC_BATCH_SIZE } from './merkle-tree.js';
+/**
+ * Client for connecting to peer servers for sync operations.
+ * Supports both direct (in-process) and HTTP transports.
+ *
+ * Uses a raw Enkaku `Client<SyncProtocol>` for sync connections rather than
+ * `KubunClient`, since only sync procedures (negotiate, merkle-sync) are needed.
+ */ export class SyncClient {
+    #runtime;
+    #identity;
+    #logger;
+    #serverResolver;
+    constructor(params){
+        this.#runtime = params.runtime;
+        this.#identity = params.identity;
+        this.#logger = params.logger;
+        this.#serverResolver = params.serverResolver;
+    }
+    /**
+   * Connect to a peer server using the specified endpoint.
+   * - `direct://server-id` - Use in-process direct transport via sync server
+   * - `http://...` or `https://...` - Use HTTP transport
+   */ async connect(endpoint, serverID) {
+        if (endpoint.startsWith('direct://')) {
+            return this.#connectDirect(endpoint);
+        }
+        if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+            return this.#connectHTTP(endpoint, serverID);
+        }
+        throw new Error(`Unsupported endpoint scheme: ${endpoint}`);
+    }
+    #connectHTTP(endpoint, serverID) {
+        if (serverID == null || serverID === '') {
+            throw new Error('HTTP sync transport requires a serverID (peer DID) to authenticate; without it the server rejects all requests');
+        }
+        const transport = new HTTPClientTransport({
+            url: endpoint,
+            fetch: this.#runtime.fetch
+        });
+        return new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        });
+    }
+    async #connectDirect(endpoint) {
+        const serverID = endpoint.replace('direct://', '');
+        if (!this.#serverResolver) {
+            throw new Error('Server resolver not configured for direct transport');
+        }
+        const provider = this.#serverResolver(serverID);
+        if (!provider) {
+            throw new Error(`Server not found: ${serverID}`);
+        }
+        // Get a sync-specific transport from the peer's p2p plugin. The provider may
+        // build the transport asynchronously (e.g. the hub-tunnel provider derives
+        // its epoch-bound inbox topics from the live MLS handle), so await it; an
+        // in-process provider returning a transport synchronously is unaffected.
+        const transport = await provider.createSyncTransport();
+        return new Client({
+            runtime: this.#runtime,
+            identity: this.#identity,
+            logger: this.#logger.getChild('sync-client'),
+            serverID,
+            transport
+        });
+    }
+    /**
+   * Negotiate sync scopes with peer.
+   */ async negotiate(client, scopes, delegationTokens = [], knownModelIDs, direction) {
+        this.#logger.debug('Negotiate: sending {scopeCount} scopes', {
+            scopeCount: scopes.length
+        });
+        const result = await client.request('sync/negotiate', {
+            param: {
+                scopes,
+                delegationTokens,
+                knownModelIDs,
+                direction
+            }
+        });
+        this.#logger.debug('Negotiate: accepted {acceptedCount} scopes, excluded {excludedCount} docs', {
+            acceptedCount: result.acceptedScopes.length,
+            excludedCount: result.excludedDocumentIDs.length
+        });
+        return result;
+    }
+    /**
+   * Perform Merkle tree-based sync with peer using bidirectional channel.
+   * Sends local tree and divergent mutations, receives remote mutations.
+   */ async merkleSync(client, params) {
+        const { scopes, excludedDocumentIDs, localTree, direction, localEntries, delegationTokens } = params;
+        this.#logger.debug('MerkleSync: creating channel with {buckets} local buckets', {
+            buckets: Object.keys(localTree.buckets).length
+        });
+        const channelCall = client.createChannel('sync/merkle-sync', {
+            param: {
+                scopes,
+                excludedDocumentIDs,
+                tree: localTree.buckets,
+                direction,
+                ...delegationTokens != null && {
+                    delegationTokens
+                }
+            }
+        });
+        // Step 1: Read the responder's tree from the first message
+        const reader = channelCall.readable.getReader();
+        const firstRead = await reader.read();
+        if (firstRead.done) {
+            throw new Error('MerkleSync: channel closed before receiving remote tree');
+        }
+        const firstMessage = firstRead.value;
+        if (firstMessage.type !== 'tree') {
+            throw new Error(`MerkleSync: expected 'tree' message, got '${firstMessage.type}'`);
+        }
+        // Step 2: Compute divergent buckets
+        const remoteTree = {
+            root: firstMessage.tree?.root ?? '',
+            buckets: firstMessage.tree ?? {}
+        };
+        const divergentBuckets = findDivergentBuckets(localTree, remoteTree);
+        const divergentBucketCount = divergentBuckets.length;
+        this.#logger.debug('MerkleSync: found {count} divergent buckets', {
+            count: divergentBucketCount
+        });
+        // Step 3: Concurrent send and receive
+        let mutationsSent = 0;
+        // Send task: send divergent mutations to responder
+        const sendTask = async ()=>{
+            if (direction === 'push' || direction === 'both') {
+                // Filter local entries to those in divergent buckets
+                const divergentSet = new Set(divergentBuckets);
+                const entriesToSend = localEntries.filter((entry)=>{
+                    const { minute } = getTimeBuckets(entry.hlc);
+                    return divergentSet.has(minute);
+                });
+                // Send in batches
+                for(let i = 0; i < entriesToSend.length; i += SYNC_BATCH_SIZE){
+                    const batch = entriesToSend.slice(i, i + SYNC_BATCH_SIZE);
+                    await channelCall.send({
+                        type: 'mutations',
+                        mutationJWTs: batch.map((e)=>e.mutation_jwt)
+                    });
+                    mutationsSent += batch.length;
+                }
+            }
+            // Signal completion
+            await channelCall.send({
+                type: 'complete'
+            });
+        };
+        // Receive task: collect mutations from responder
+        const receiveTask = async ()=>{
+            const collectedJWTs = [];
+            while(true){
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (value.type === 'mutations' && value.mutationJWTs != null) {
+                    collectedJWTs.push(...value.mutationJWTs);
+                } else if (value.type === 'complete') {
+                    break;
+                }
+            }
+            reader.releaseLock();
+            return collectedJWTs;
+        };
+        const [, mutationJWTs] = await Promise.all([
+            sendTask(),
+            receiveTask()
+        ]);
+        // Wait for the handler to finish processing (applying pushed mutations)
+        // before returning — prevents transport teardown racing with mutation application
+        const handlerResult = await channelCall;
+        if (handlerResult != null && !handlerResult.success) {
+            throw new Error('MerkleSync: responder reported failure');
+        }
+        this.#logger.debug('MerkleSync: completed with {received} received, {sent} sent', {
+            received: mutationJWTs.length,
+            sent: mutationsSent
+        });
+        return {
+            mutationJWTs,
+            divergentBuckets: divergentBucketCount,
+            mutationsSent
+        };
+    }
+}

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

@@ -1,8 +1,8 @@
-import type { Runtime } from '@enkaku/runtime';
-import { type Identity, type SigningIdentity } from '@enkaku/token';
+import { type Identity, type SigningIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { Logger } from '@kubun/logger';
+import type { Runtime } from '@sozai/runtime';
 import type { SyncDirection } from '../protocol.js';
 import type { StoreUnreadableMode } from '../types.js';
 import { type PeerConfig, type PeerConfigWithID, PeerRegistry } from './peer-registry.js';

package/lib/sync/sync-manager.js

@@ -1 +1,272 @@
-import{EventEmitter as e}from"@enkaku/event";import{isSigningIdentity as t}from"@enkaku/token";import{getGraphStore as s}from"@kubun/store-graph";import{applySyncMutations as r}from"./merkle-apply.js";import{buildMerkleTree as i}from"./merkle-tree.js";import{PeerRegistry as n}from"./peer-registry.js";import{SyncClient as o}from"./sync-client.js";export class SyncManager{#e;#t;#s;#r;#i;#n=new e;#o=new Map;#a=new Map;#l;#c;#g;#p;constructor(e){this.#e=e.deployClusters,this.#t=e.graph,this.#s=e.runtime,this.#l=e.identity,this.#r=e.logger,this.#i=new n({runtime:e.runtime}),this.#c=e.serverResolver,this.#g=e.storeUnreadable??"persist",this.#p=e.defaultAccessLevel}get peerRegistry(){return this.#i}setIdentity(e){this.#l=e}setServerResolver(e){this.#c=e}async addPeer(e){await this.#i.addPeer(e),this.#r.info("Peer added",{peerDID:e.config.peerDID})}async removePeer(e){await this.#i.removePeer(e),this.#r.info("Peer removed",{peerDID:e.peerDID})}async updatePeerConfig(e){await this.#i.updatePeer(e),this.#r.info("Peer updated",{peerDID:e.peerDID})}async listPeers(e){return this.#i.listPeers(e)}async getPeer(e){return this.#i.getPeer(e)}async merkleSyncWithPeer(e){let n,{peerDID:a,scopes:l,delegationTokens:c=[],knownModelIDs:g,direction:p}=e;this.#r.info("Starting Merkle sync with peer",{peerDID:a,scopes:l});let m=await this.#i.getPeer({peerDID:a,stores:e.stores});if(!m)throw Error(`Peer ${a} not found`);let d=`merkle-sync-${a}-${Date.now()}`,h={peerID:a,startTime:Date.now(),documentsAttempted:0,documentsCompleted:0};this.#o.set(d,h),this.#m({type:"started",peerID:a,timestamp:Date.now()});try{let u=this.#l;if(!t(u))throw Error("Signing identity required for Merkle sync");let y=new o({runtime:this.#s,identity:u,logger:this.#r,serverResolver:this.#c});n=await y.connect(m.endpoint,a);let v=p??"pull";this.#r.info("Negotiating sync scopes",{scopes:l,direction:v});let{acceptedScopes:f,excludedDocumentIDs:D,missingClusters:w,direction:k}=await y.negotiate(n,l,c,g,v);if(0===f.length)return this.#r.info("No scopes accepted by peer"),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#o.delete(d),{sessionID:d,divergentBuckets:0,messagesReceived:0,messagesSent:0,missingClusters:w};null!=w&&Object.keys(w).length>0&&(null!=this.#e?(this.#r.info("Deploying missing clusters from peer",{clusterCount:Object.keys(w).length}),await this.#e(w)):this.#r.warn("Missing clusters received but no deployClusters callback configured",{clusterCount:Object.keys(w).length})),this.#r.info("Building local Merkle tree",{acceptedScopes:f});let S=await s(e.stores),P=await S.getDocumentIDsForScope(f,D),R=await S.getMutationLogForDocuments(P),I=i(R),b=k??v;this.#r.info("Requesting Merkle sync from peer",{localTreeBuckets:Object.keys(I.buckets).length,direction:b});let C=await y.merkleSync(n,{scopes:f,excludedDocumentIDs:D,localTree:I,direction:b,localEntries:R});return C.mutationJWTs.length>0&&(this.#r.info("Applying sync mutations",{mutations:C.mutationJWTs.length}),h.documentsCompleted=(await r({db:e.stores,graph:this.#t,mutationJWTs:C.mutationJWTs,selfDID:this.#l.id,storeUnreadable:this.#g,defaultAccessLevel:this.#p})).applied),this.#a.set(a,Date.now()),this.#m({type:"completed",peerID:a,timestamp:Date.now()}),this.#r.info("Merkle sync completed",{divergentBuckets:C.divergentBuckets,mutationsReceived:C.mutationJWTs.length}),{sessionID:d,divergentBuckets:C.divergentBuckets,messagesReceived:C.mutationJWTs.length,messagesSent:C.mutationsSent,missingClusters:w}}catch(e){throw this.#r.error("Merkle sync failed",{peerDID:a,error:e}),this.#m({type:"error",peerID:a,timestamp:Date.now(),error:e instanceof Error?e.message:String(e)}),e}finally{if(null!=n)try{n.abort("SyncComplete"),await n.dispose()}catch{}this.#o.delete(d)}}getStatus(e){let{peerDID:t}=e,s=Array.from(this.#o.values()).filter(e=>!t||e.peerID===t).map(e=>({peerID:e.peerID,startTime:e.startTime,documentsAttempted:e.documentsAttempted,documentsCompleted:e.documentsCompleted})),r={};for(let[e,s]of this.#a.entries())t&&e!==t||(r[e]=s);return{activeSessions:s,lastSyncByPeer:r}}onSyncEvent(e){return this.#n.on("sync",e)}#m(e){this.#n.emit("sync",e).catch(e=>{this.#r.error("Error in sync event listener",{error:e})})}async dispose(){this.#o.clear(),this.#a.clear()}}
+import { isSigningIdentity } from '@kokuin/token';
+import { getGraphStore } from '@kubun/store-graph';
+import { EventEmitter } from '@sozai/event';
+import { applySyncMutations } from './merkle-apply.js';
+import { buildMerkleTree } from './merkle-tree.js';
+import { PeerRegistry } from './peer-registry.js';
+import { SyncClient } from './sync-client.js';
+export class SyncManager {
+    #deployClusters;
+    #graph;
+    #runtime;
+    #logger;
+    #peerRegistry;
+    #events = new EventEmitter();
+    #activeSessions = new Map();
+    #lastSyncByPeer = new Map();
+    #identity;
+    #serverResolver;
+    #storeUnreadable;
+    #defaultAccessLevel;
+    constructor(params){
+        this.#deployClusters = params.deployClusters;
+        this.#graph = params.graph;
+        this.#runtime = params.runtime;
+        this.#identity = params.identity;
+        this.#logger = params.logger;
+        this.#peerRegistry = new PeerRegistry({
+            runtime: params.runtime
+        });
+        this.#serverResolver = params.serverResolver;
+        this.#storeUnreadable = params.storeUnreadable ?? 'persist';
+        this.#defaultAccessLevel = params.defaultAccessLevel;
+    }
+    get peerRegistry() {
+        return this.#peerRegistry;
+    }
+    /**
+   * Configure the signing identity used for sync operations.
+   */ setIdentity(identity) {
+        this.#identity = identity;
+    }
+    /**
+   * Configure the server resolver for direct transport connections.
+   */ setServerResolver(resolver) {
+        this.#serverResolver = resolver;
+    }
+    // ---- Peer management (delegates to PeerRegistry) ----
+    async addPeer(params) {
+        await this.#peerRegistry.addPeer(params);
+        this.#logger.info('Peer added', {
+            peerDID: params.config.peerDID
+        });
+    }
+    async removePeer(params) {
+        await this.#peerRegistry.removePeer(params);
+        this.#logger.info('Peer removed', {
+            peerDID: params.peerDID
+        });
+    }
+    async updatePeerConfig(params) {
+        await this.#peerRegistry.updatePeer(params);
+        this.#logger.info('Peer updated', {
+            peerDID: params.peerDID
+        });
+    }
+    async listPeers(params) {
+        return this.#peerRegistry.listPeers(params);
+    }
+    async getPeer(params) {
+        return this.#peerRegistry.getPeer(params);
+    }
+    // ---- Sync orchestration ----
+    async merkleSyncWithPeer(params) {
+        const { peerDID, scopes, delegationTokens = [], knownModelIDs, direction: requestedDirection } = params;
+        this.#logger.info('Starting Merkle sync with peer', {
+            peerDID,
+            scopes
+        });
+        const peer = await this.#peerRegistry.getPeer({
+            peerDID,
+            stores: params.stores
+        });
+        if (!peer) {
+            throw new Error(`Peer ${peerDID} not found`);
+        }
+        const sessionID = `merkle-sync-${peerDID}-${Date.now()}`;
+        const sessionData = {
+            peerID: peerDID,
+            startTime: Date.now(),
+            documentsAttempted: 0,
+            documentsCompleted: 0
+        };
+        this.#activeSessions.set(sessionID, sessionData);
+        this.#emitEvent({
+            type: 'started',
+            peerID: peerDID,
+            timestamp: Date.now()
+        });
+        let client;
+        try {
+            const identity = this.#identity;
+            if (!isSigningIdentity(identity)) {
+                throw new Error('Signing identity required for Merkle sync');
+            }
+            const syncClient = new SyncClient({
+                runtime: this.#runtime,
+                identity,
+                logger: this.#logger,
+                serverResolver: this.#serverResolver
+            });
+            client = await syncClient.connect(peer.endpoint, peerDID);
+            // Step 1: Negotiate scopes
+            const direction = requestedDirection ?? 'pull';
+            this.#logger.info('Negotiating sync scopes', {
+                scopes,
+                direction
+            });
+            const { acceptedScopes, excludedDocumentIDs, missingClusters, direction: agreedDirection } = await syncClient.negotiate(client, scopes, delegationTokens, knownModelIDs, direction);
+            if (acceptedScopes.length === 0) {
+                this.#logger.info('No scopes accepted by peer');
+                this.#lastSyncByPeer.set(peerDID, Date.now());
+                this.#emitEvent({
+                    type: 'completed',
+                    peerID: peerDID,
+                    timestamp: Date.now()
+                });
+                this.#activeSessions.delete(sessionID);
+                return {
+                    sessionID,
+                    divergentBuckets: 0,
+                    messagesReceived: 0,
+                    messagesSent: 0,
+                    missingClusters
+                };
+            }
+            // Step 1b: Deploy missing clusters before building merkle tree
+            if (missingClusters != null && Object.keys(missingClusters).length > 0) {
+                if (this.#deployClusters != null) {
+                    this.#logger.info('Deploying missing clusters from peer', {
+                        clusterCount: Object.keys(missingClusters).length
+                    });
+                    await this.#deployClusters(missingClusters);
+                } else {
+                    this.#logger.warn('Missing clusters received but no deployClusters callback configured', {
+                        clusterCount: Object.keys(missingClusters).length
+                    });
+                }
+            }
+            // Step 2: Build local Merkle tree for accepted scopes
+            this.#logger.info('Building local Merkle tree', {
+                acceptedScopes
+            });
+            const graphStore = await getGraphStore(params.stores);
+            const documentIDs = await graphStore.getDocumentIDsForScope(acceptedScopes, excludedDocumentIDs);
+            const localEntries = await graphStore.getMutationLogForDocuments(documentIDs);
+            const localTree = buildMerkleTree(localEntries);
+            // Step 3: Sync with peer via bidirectional channel
+            const syncDirection = agreedDirection ?? direction;
+            this.#logger.info('Requesting Merkle sync from peer', {
+                localTreeBuckets: Object.keys(localTree.buckets).length,
+                direction: syncDirection
+            });
+            const syncResult = await syncClient.merkleSync(client, {
+                scopes: acceptedScopes,
+                excludedDocumentIDs,
+                localTree,
+                direction: syncDirection,
+                localEntries,
+                // Forward the same delegation tokens used during negotiate so the
+                // merkle-sync access gate authorizes the accepted non-owned scopes. A
+                // revocation landing between negotiate and sync fails the sync; the
+                // retry renegotiates with the updated revocation state.
+                delegationTokens
+            });
+            // Step 4: Apply received mutation JWTs locally
+            if (syncResult.mutationJWTs.length > 0) {
+                this.#logger.info('Applying sync mutations', {
+                    mutations: syncResult.mutationJWTs.length
+                });
+                const applyResult = await applySyncMutations({
+                    db: params.stores,
+                    graph: this.#graph,
+                    mutationJWTs: syncResult.mutationJWTs,
+                    selfDID: this.#identity.id,
+                    storeUnreadable: this.#storeUnreadable,
+                    defaultAccessLevel: this.#defaultAccessLevel
+                });
+                sessionData.documentsCompleted = applyResult.applied;
+                if (applyResult.deferred > 0) {
+                    this.#logger.info('Deferred sync mutations for retry next round', {
+                        deferred: applyResult.deferred
+                    });
+                }
+            }
+            this.#lastSyncByPeer.set(peerDID, Date.now());
+            this.#emitEvent({
+                type: 'completed',
+                peerID: peerDID,
+                timestamp: Date.now()
+            });
+            this.#logger.info('Merkle sync completed', {
+                divergentBuckets: syncResult.divergentBuckets,
+                mutationsReceived: syncResult.mutationJWTs.length
+            });
+            return {
+                sessionID,
+                divergentBuckets: syncResult.divergentBuckets,
+                messagesReceived: syncResult.mutationJWTs.length,
+                messagesSent: syncResult.mutationsSent,
+                missingClusters
+            };
+        } catch (error) {
+            this.#logger.error('Merkle sync failed', {
+                peerDID,
+                error
+            });
+            this.#emitEvent({
+                type: 'error',
+                peerID: peerDID,
+                timestamp: Date.now(),
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        } finally{
+            if (client != null) {
+                try {
+                    client.abort('SyncComplete');
+                    await client.dispose();
+                } catch  {
+                // Transport may already be closed
+                }
+            }
+            this.#activeSessions.delete(sessionID);
+        }
+    }
+    // ---- Status ----
+    getStatus(params) {
+        const { peerDID } = params;
+        const sessions = Array.from(this.#activeSessions.values()).filter((s)=>!peerDID || s.peerID === peerDID).map((data)=>({
+                peerID: data.peerID,
+                startTime: data.startTime,
+                documentsAttempted: data.documentsAttempted,
+                documentsCompleted: data.documentsCompleted
+            }));
+        const lastSyncByPeer = {};
+        for (const [peer, time] of this.#lastSyncByPeer.entries()){
+            if (!peerDID || peer === peerDID) {
+                lastSyncByPeer[peer] = time;
+            }
+        }
+        return {
+            activeSessions: sessions,
+            lastSyncByPeer
+        };
+    }
+    // ---- Events ----
+    onSyncEvent(callback) {
+        return this.#events.on('sync', callback);
+    }
+    #emitEvent(event) {
+        this.#events.emit('sync', event).catch((error)=>{
+            this.#logger.error('Error in sync event listener', {
+                error
+            });
+        });
+    }
+    // ---- Lifecycle ----
+    async dispose() {
+        this.#activeSessions.clear();
+        this.#lastSyncByPeer.clear();
+    }
+}

package/lib/types.d.ts

@@ -101,6 +101,17 @@ export type GroupRequestContext = {
     list: () => Promise<Array<GroupData>>;
     get: (id: string) => Promise<GroupData | null>;
     addMember: (groupID: string, memberDID: string, role: string) => Promise<GroupMemberData>;
+    /**
+     * Promote a member to admin or demote them back to member by emitting a
+     * self-signed `group.role.admin` ledger entry. Authority is rooted at the
+     * group's genesis anchor and folded on every peer, so a non-admin caller is
+     * rejected and the change converges identically across the group.
+     */
+    setMemberRole: (params: {
+        groupID: string;
+        memberDID: string;
+        role: 'admin' | 'member';
+    }) => Promise<GroupMemberData>;
     listMembers: (groupID: string) => Promise<Array<GroupMemberData>>;
     createCircle: (params: {
         groupID: string;
@@ -230,6 +241,14 @@ export type HubRequestContext = {
     }) => Promise<boolean>;
     listByGroup: (groupID: string) => Promise<Array<HubData>>;
     listGroups: (hubID: string) => Promise<Array<GroupData>>;
+    /** Current health snapshot for a group (state + last transition time). */
+    getGroupHealth: (groupID: string) => GroupHealthSnapshot;
+    /**
+     * Kick off stale-device recovery for a group. Fire-and-forget at the resolver
+     * boundary; the terminal outcome arrives via the `groupHealthChanged`
+     * subscription. Resolves with the flow's final result for callers that await.
+     */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
 };
 export type DelegationData = {
     jwt: string;
@@ -285,6 +304,28 @@ export type SyncSessionResult = {
     messagesSent: number;
     missingClusters?: Record<string, unknown>;
 };
+/** A group-level health condition the monitor tracks. */
+export type GroupHealthCondition = 'epoch-stale';
+/**
+ * Persisted health state for a group. `recovered` is a transient transition
+ * surfaced only on the emitted event; `getState` collapses it to `healthy`.
+ */
+export type GroupHealthState = 'healthy' | 'degraded' | 'recovering' | 'recovered' | 'recovery-failed';
+export type GroupHealthData = {
+    groupID: string;
+    condition: GroupHealthCondition;
+    state: GroupHealthState;
+};
+/** A point-in-time health snapshot for a group (drives the GraphQL query). */
+export type GroupHealthSnapshot = {
+    state: GroupHealthState;
+    /** Epoch ms of the last state transition, or null if never transitioned. */
+    lastTransitionAt: number | null;
+};
+/** Terminal outcome of a rejoin flow. */
+export type RejoinResult = {
+    status: 'recovered' | 'recovery-failed';
+};
 export type SyncPluginAPI = {
     /** Resolves when the HTTP sync transport is registered (only present when http option is enabled). */
     syncReady?: Promise<void>;

package/lib/types.js

@@ -1 +1,2 @@
-export{};
+// ---- Plugin API ----
+export { };

package/lib/util/mutex.js

@@ -1 +1,10 @@
-export function createMutex(){let e=Promise.resolve();return{run(t){let r=e.then(()=>t());return e=r.catch(()=>{}),r}}}
+export function createMutex() {
+    let tail = Promise.resolve();
+    return {
+        run (fn) {
+            const next = tail.then(()=>fn());
+            tail = next.catch(()=>{});
+            return next;
+        }
+    };
+}

package/lib/utils.d.ts

@@ -0,0 +1,5 @@
+/** Node returns a Timeout object with `unref()`; browsers return a number. */
+export declare function unref(timer: ReturnType<typeof setTimeout>): void;
+/** Resolve after `ms`, without keeping the process alive. */
+export declare function sleep(ms: number): Promise<void>;
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;

package/lib/utils.js

@@ -0,0 +1,21 @@
+/** Node returns a Timeout object with `unref()`; browsers return a number. */ export function unref(timer) {
+    ;
+    timer.unref?.();
+}
+/** Resolve after `ms`, without keeping the process alive. */ export function sleep(ms) {
+    return new Promise((resolve)=>{
+        const timer = setTimeout(resolve, ms);
+        unref(timer);
+    });
+}
+export function bytesEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for(let i = 0; i < a.length; i++){
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}