@kubun/plugin-p2p 0.10.0 → 0.10.1

package/lib/hub/circle-catchup-requester.d.ts

@@ -0,0 +1,58 @@
+import type { Logger } from '@kubun/logger';
+import type { GroupBroadcastMessage } from '../groups/broadcast.js';
+/** The reply payload a current member sends back, correlated by `requestID`. */
+type CatchupReply = Extract<GroupBroadcastMessage, {
+    type: 'circle-catchup:reply';
+}>;
+export type CircleCatchupRequesterParams = {
+    groupID: string;
+    /** Fresh correlation id per request (incl. retries). */
+    genRequestID: () => string;
+    /** Broadcast a `circle-catchup:request` on the group channel. */
+    sendRequest: (requestID: string) => Promise<void>;
+    /**
+     * Apply a received reply batch row-by-row (idempotent, order-independent).
+     * Mirrors `applyCatchupReply` bound to the local store/engine context.
+     */
+    applyReply: (reply: CatchupReply) => Promise<void>;
+    requestTimeoutMs?: number;
+    maxAttempts?: number;
+    backoffMs?: (attempt: number) => number;
+    logger?: Logger;
+};
+/**
+ * Drives a rejoining device's circle/member catch-up for one group: broadcast a
+ * `circle-catchup:request`, await the first matching `circle-catchup:reply`
+ * (correlated by `requestID`) within a timeout, apply it, done. On timeout,
+ * retry with a capped full-jitter backoff up to `maxAttempts`.
+ *
+ * Mirrors the rejoin manager's request/await/retry shape, minus any MLS
+ * join/confirm — there is no Commit to broadcast and no head to confirm against,
+ * because `applyReply` is idempotent and order-independent: one good reply
+ * lands the snapshot, and a duplicate or late reply is a harmless no-op.
+ *
+ * Exhaustion is NON-FATAL: a device that never hears back simply keeps the
+ * state it has; it resolves without throwing.
+ */
+export declare class CircleCatchupRequester {
+    #private;
+    constructor(params: CircleCatchupRequesterParams);
+    get inFlight(): boolean;
+    /**
+     * Route a received `circle-catchup:reply`: resolve the matching in-flight
+     * waiter. Unknown `requestID`s (peers' requests, stale or duplicate replies
+     * for an already-resolved attempt) are ignored — harmless.
+     */
+    onCatchupReply(requestID: string, reply: CatchupReply): void;
+    /**
+     * Run the catch-up flow. Idempotent: a concurrent call while one is in flight
+     * shares the existing run's promise rather than starting a second.
+     */
+    run(): Promise<void>;
+    /**
+     * Stop a running catch-up and release timers. Idempotent; the loop checks
+     * `#disposed` between attempts, pending waiters resolve `null`. On channel close.
+     */
+    dispose(): void;
+}
+export {};

package/lib/hub/circle-catchup-requester.js

@@ -0,0 +1 @@
+import{sleep as e,unref as t}from"../utils.js";export class CircleCatchupRequester{#e;#t;#s;#i;#r;#l;#a;#u;#n=new Map;#o=null;#h=!1;constructor(e){this.#e=e.groupID,this.#t=e.genRequestID,this.#s=e.sendRequest,this.#i=e.applyReply,this.#r=e.requestTimeoutMs??5e3,this.#l=e.maxAttempts??8,this.#a=e.backoffMs??s,this.#u=e.logger}get inFlight(){return null!=this.#o}onCatchupReply(e,t){let s=this.#n.get(e);null!=s&&(this.#n.delete(e),s.resolve(t))}run(){if(null!=this.#o)return this.#o;let e=this.#p().finally(()=>{this.#o=null});return this.#o=e,e}async #p(){for(let t=0;t<this.#l&&!this.#h;t++){if(t>0&&(await e(this.#a(t)),this.#h))return;let s=await this.#c(this.#r);if(null!=s)try{await this.#i(s);return}catch(e){this.#u?.warn("circle catch-up: applying reply failed",{groupID:this.#e,error:e})}}this.#h||this.#u?.warn("circle catch-up: no usable reply, giving up",{groupID:this.#e,attempts:this.#l})}async #c(e){let t=this.#t(),s=this.#g(t,e);try{await this.#s(t)}catch(e){return this.#m(t),this.#u?.warn("circle catch-up: request send failed",{groupID:this.#e,error:e}),null}return s}#g(e,s){return new Promise(i=>{let r=setTimeout(()=>{this.#n.delete(e),i(null)},s);t(r),this.#n.set(e,{resolve:e=>{clearTimeout(r),i(e)},cancel:()=>{clearTimeout(r),i(null)}})})}#m(e){let t=this.#n.get(e);null!=t&&(this.#n.delete(e),t.cancel())}dispose(){for(let e of(this.#h=!0,this.#n.values()))e.cancel();this.#n.clear()}}function s(e){return Math.floor(Math.random()*Math.min(500*2**(e-1),5e3))}

package/lib/hub/circle-catchup-responder.d.ts

@@ -0,0 +1,50 @@
+import type { Logger } from '@kubun/logger';
+import type { Circle, CircleMember } from '@kubun/store-p2p';
+import type { CircleMemberSnapshot, CircleSnapshot } from '../groups/broadcast.js';
+/**
+ * Reads the group's circles + circle members from the store. Mirrors the
+ * `listCirclesByGroup` / `listCircleMembers` store API, both returning
+ * tombstoned rows when `includeRemoved` is set so the snapshot can carry
+ * removed entries.
+ */
+export type CircleCatchupStoreReader = {
+    listCirclesByGroup: (groupID: string, options?: {
+        includeRemoved?: boolean;
+    }) => Promise<Array<Circle>>;
+    listCircleMembers: (circleID: string, options?: {
+        includeRemoved?: boolean;
+    }) => Promise<Array<CircleMember>>;
+};
+export type CircleCatchupResponderParams = {
+    groupID: string;
+    /** Reads the group's circle + circle-member rows (including tombstoned). */
+    store: CircleCatchupStoreReader;
+    /** Broadcast a `circle-catchup:reply` to the group channel. */
+    sendCatchupReply: (requestID: string, circles: Array<CircleSnapshot>, circleMembers: Array<CircleMemberSnapshot>) => Promise<void>;
+    /** Jitter delay (ms) before replying. Defaults to a random 0..250ms. */
+    nextJitterMs?: () => number;
+    /** How long a `requestID` stays suppressed after being answered. */
+    suppressTTLMs?: number;
+    logger?: Logger;
+};
+/**
+ * Answers `circle-catchup:request`s with one batched snapshot of the group's
+ * circle + circle-member rows (including tombstoned, each carrying its authored
+ * HLC). Every current member could reply, so jitter (random pre-reply delay) +
+ * suppression (cancel on seeing a peer's reply for the same `requestID`)
+ * collapse the storm to ~1 reply. Keyed on `requestID` (fresh per attempt);
+ * suppression entries TTL out to bound memory.
+ *
+ * Mirrors the rejoin responder's storm-collapse shape; suppression collapses
+ * only duplicates of one `requestID`, so distinct `requestID`s still draw one
+ * reply each.
+ */
+export declare class CircleCatchupResponder {
+    #private;
+    constructor(params: CircleCatchupResponderParams);
+    /** Handle an inbound `circle-catchup:request`: schedule a jittered, suppressible reply. */
+    onCatchupRequest(requestID: string): void;
+    /** Handle an observed `circle-catchup:reply` (own or peer's): suppress this request. */
+    onCatchupReplySeen(requestID: string): void;
+    dispose(): void;
+}

package/lib/hub/circle-catchup-responder.js

@@ -0,0 +1 @@
+import{unref as e}from"../utils.js";function s(e){return{id:e.id,groupID:e.group_id,name:e.name,description:e.description,catalogIDs:e.catalog_ids,hlc:e.hlc,removedAtHLC:e.removed_at_hlc??null}}export class CircleCatchupResponder{#e;#s;#t;#r;#i;#p;#o=new Map;#l=new Map;constructor(e){this.#e=e.groupID,this.#s=e.store,this.#t=e.sendCatchupReply,this.#r=e.nextJitterMs??(()=>Math.floor(250*Math.random())),this.#i=e.suppressTTLMs??5e3,this.#p=e.logger}onCatchupRequest(s){if(this.#l.has(s)||this.#o.has(s))return;let t=setTimeout(()=>{this.#o.delete(s),this.#h(s)},this.#r());e(t),this.#o.set(s,t)}onCatchupReplySeen(e){let s=this.#o.get(e);null!=s&&(clearTimeout(s),this.#o.delete(e)),this.#n(e)}dispose(){for(let e of this.#o.values())clearTimeout(e);for(let e of(this.#o.clear(),this.#l.values()))clearTimeout(e);this.#l.clear()}async #h(e){if(!this.#l.has(e)){this.#n(e);try{let{circles:s,circleMembers:t}=await this.#u();await this.#t(e,s,t)}catch(s){this.#p?.warn("circle catch-up responder failed to reply",{groupID:this.#e,requestID:e,error:s})}}}async #u(){let e=await this.#s.listCirclesByGroup(this.#e,{includeRemoved:!0}),t=e.map(s),r=[];for(let s of e)for(let e of(await this.#s.listCircleMembers(s.id,{includeRemoved:!0})))r.push({circleID:e.circle_id,memberDID:e.member_did,role:e.role,hlc:e.hlc,removedAtHLC:e.removed_at_hlc??null});return{circles:t,circleMembers:r}}#n(s){let t=this.#l.get(s);null!=t&&clearTimeout(t);let r=setTimeout(()=>{this.#l.delete(s)},this.#i);e(r),this.#l.set(s,r)}}

package/lib/hub/epoch-stale-detector.d.ts

@@ -0,0 +1,18 @@
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { ReceiveOutcome } from './receive-handler.js';
+export type EpochStaleDetectorParams = {
+    groupID: string;
+    monitor: GroupHealthMonitor;
+};
+/**
+ * Maps a group's receive outcomes to `epoch-stale` signals (one per group):
+ * `applied` → reset; `decrypt-failed` → signal; `commit-out-of-order` → signal
+ * only on a REPEAT `sequenceID` (first sighting is normal replay; a repeat means
+ * the gap-filling Commit was GC'd at the hub and never arrives); else no signal.
+ * The seen-set grows only while stuck and clears on the next `applied`.
+ */
+export declare class EpochStaleDetector {
+    #private;
+    constructor(params: EpochStaleDetectorParams);
+    onReceiveOutcome(outcome: ReceiveOutcome, sequenceID: string): void;
+}

package/lib/hub/epoch-stale-detector.js

@@ -0,0 +1 @@
+export class EpochStaleDetector{#e;#t;#r=new Set;constructor(e){this.#e=e.groupID,this.#t=e.monitor}onReceiveOutcome(e,t){switch(e){case"applied":this.#r.clear(),this.#t.reset(this.#e,"epoch-stale");return;case"decrypt-failed":this.#t.signal(this.#e,"epoch-stale");return;case"commit-out-of-order":this.#r.has(t)?this.#t.signal(this.#e,"epoch-stale"):this.#r.add(t);return;default:return}}}

package/lib/hub/errors.d.ts

@@ -1,7 +1,8 @@
 export declare class ReconnectingError extends Error {
-    readonly hubURL: string;
-    readonly attempt: number;
+    #private;
     constructor(hubURL: string, attempt: number);
+    get hubURL(): string;
+    get attempt(): number;
 }
 /**
  * Thrown by `DIDObservingTransport.read()` when the first observed `payload.iss`
@@ -17,12 +18,13 @@ export declare class ReconnectingError extends Error {
  * message is delivered, when a row was already pinned at connect time.
  */
 export declare class HubServerDIDMismatchError extends Error {
-    readonly hubURL: string;
-    readonly expectedServerDID: string;
-    readonly observedServerDID: string;
+    #private;
     constructor(params: {
         hubURL: string;
         expectedServerDID: string;
         observedServerDID: string;
     });
+    get hubURL(): string;
+    get expectedServerDID(): string;
+    get observedServerDID(): string;
 }

package/lib/hub/errors.js

@@ -1 +1 @@
-export class ReconnectingError extends Error{hubURL;attempt;constructor(e,r){super(`broadcast wait timed out: hub ${e} reconnecting (attempt ${r})`),this.name="ReconnectingError",this.hubURL=e,this.attempt=r}}export class HubServerDIDMismatchError extends Error{hubURL;expectedServerDID;observedServerDID;constructor(e){super(`hub at ${e.hubURL} signed responses with ${e.observedServerDID}; pinned to ${e.expectedServerDID}`),this.name="HubServerDIDMismatchError",this.hubURL=e.hubURL,this.expectedServerDID=e.expectedServerDID,this.observedServerDID=e.observedServerDID}}
+export class ReconnectingError extends Error{#e;#r;constructor(e,r){super(`broadcast wait timed out: hub ${e} reconnecting (attempt ${r})`),this.name="ReconnectingError",this.#e=e,this.#r=r}get hubURL(){return this.#e}get attempt(){return this.#r}}export class HubServerDIDMismatchError extends Error{#e;#t;#s;constructor(e){super(`hub at ${e.hubURL} signed responses with ${e.observedServerDID}; pinned to ${e.expectedServerDID}`),this.name="HubServerDIDMismatchError",this.#e=e.hubURL,this.#t=e.expectedServerDID,this.#s=e.observedServerDID}get hubURL(){return this.#e}get expectedServerDID(){return this.#t}get observedServerDID(){return this.#s}}

package/lib/hub/group-channel.d.ts

@@ -1,9 +1,13 @@
 import { Disposer } from '@enkaku/async';
+import type { OwnIdentity } from '@enkaku/token';
 import type { Logger } from '@kubun/logger';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
 import type { BroadcastService } from '../groups/broadcast-service.js';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.js';
 import type { HubConnection } from './hub-connection.js';
+import { RejoinManager } from './rejoin-manager.js';
 export type AckBatchParams = {
     flushMs: number;
     flushMax: number;
@@ -32,6 +36,19 @@ export type GroupChannelParams = {
     broadcastService: BroadcastService;
     p2pStore: P2PStoreAPI;
     logger?: Logger;
+    /** When provided, receive outcomes feed epoch-stale health detection and the
+     *  rejoin flow becomes available (both need the shared health monitor). */
+    monitor?: GroupHealthMonitor;
+    /** Device identity — required by `joinGroupExternal` in the rejoin flow. */
+    identity?: OwnIdentity;
+    /** Fresh correlation ids for rejoin requests. */
+    getRandomID?: () => string;
+    /**
+     * Pre-built rejoin manager, overriding the one this channel would construct
+     * from `monitor`/`identity`/`getRandomID`. Lets the rejoin orchestration be
+     * driven without standing up real MLS; production callers leave it unset.
+     */
+    rejoinManager?: RejoinManager;
 };
 /**
  * Per-group handle: thin wrapper around a shared `HubConnection`.
@@ -52,6 +69,11 @@ export declare class GroupChannel extends Disposer {
     #private;
     constructor(params: GroupChannelParams);
     open(): Promise<void>;
+    /**
+     * Run stale-device recovery for this group. Available only when constructed
+     * with a health monitor + identity; returns `recovery-failed` otherwise.
+     */
+    rejoinGroup(): Promise<RejoinResult>;
     close(): Promise<void>;
     broadcast(message: GroupBroadcastMessage, opts?: {
         timeoutMs?: number;

package/lib/hub/group-channel.js

@@ -1 +1 @@
-import{Disposer as e}from"@enkaku/async";import{handleReceivedMessage as t}from"./receive-handler.js";import{handleSendBroadcast as r,handleSendCommit as i}from"./send-handler.js";export class AckBatch{#e;#t;#r;#i;#s=new Set;#o=null;constructor(e){this.#e=e.flushMs,this.#t=e.flushMax,this.#r=e.send,this.#i=e.logger}add(e){let t=0===this.#s.size;if(this.#s.add(e),this.#s.size>=this.#t){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.flush();return}t&&null===this.#o&&(this.#o=setTimeout(()=>{this.#o=null,this.flush()},this.#e))}async flush(){if(null!==this.#o&&(clearTimeout(this.#o),this.#o=null),0===this.#s.size)return;let e=Array.from(this.#s);this.#s.clear();try{await this.#r(e)}catch(t){this.#i?.error("ack batch send failed",{error:t,count:e.length})}}dispose(){null!==this.#o&&(clearTimeout(this.#o),this.#o=null),this.#s.clear()}}export function computeBackoff(e,t,r,i){let s=Math.min(t*2**e*(1+i*(2*Math.random()-1)),r);return s<0?0:s}export function abortableSleep(e,t){return new Promise((r,i)=>{if(t.aborted)return void i(t.reason??Error("aborted"));let s=setTimeout(()=>{t.removeEventListener("abort",o),r()},e),o=()=>{clearTimeout(s),t.removeEventListener("abort",o),i(t.reason??Error("aborted"))};t.addEventListener("abort",o)})}export class GroupChannel extends e{#n;#h;#a;#u;#c;#i;#d=!1;constructor(e){super({dispose:async()=>{await this.#l()}}),this.#n=e.groupID,this.#h=e.deviceID,this.#a=e.hubConnection,this.#u=e.broadcastService,this.#c=e.p2pStore,this.#i=e.logger}async open(){if(this.#d)throw Error("GroupChannel already opened");let e=await this.#c.getMLSState(this.#n,this.#h);if(null==e)throw Error(`MLS state missing for group ${this.#n}; cannot join hub group`);await this.#a.subscribe(this.#n,e.credential,e=>this.#p(e)),this.#d=!0}#p(e){return t({groupID:this.#n,message:e,broadcastService:this.#u,logger:this.#i})}async close(){this.#d&&await this.dispose()}async #l(){if(this.#d){try{await this.#a.unsubscribe(this.#n)}catch(e){this.#i?.warn("hub-connection unsubscribe failed during close",{groupID:this.#n,error:e})}this.#d=!1}}broadcast(e,t){return this.#d?this.#a.runInGroup(this.#n,async()=>{if(!this.#d)throw Error(`GroupChannel for ${this.#n} is not ready for broadcast`);await r({groupID:this.#n,message:e,broadcastService:this.#u,send:(e,r)=>this.#a.broadcast(e,r,{timeoutMs:t?.timeoutMs}),logger:this.#i})},{timeoutMs:t?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for broadcast`))}sendCommit(e,t){return this.#d?this.#a.runInGroup(this.#n,async()=>{if(!this.#d)throw Error(`GroupChannel for ${this.#n} is not ready for sendCommit`);await i({groupID:this.#n,commitBytes:e,broadcastService:this.#u,send:(e,r)=>this.#a.broadcast(e,r,{timeoutMs:t?.timeoutMs}),logger:this.#i})},{timeoutMs:t?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for sendCommit`))}}
+import{Disposer as e}from"@enkaku/async";import{toB64 as r}from"@enkaku/codec";import{CircleCatchupRequester as t}from"./circle-catchup-requester.js";import{CircleCatchupResponder as o}from"./circle-catchup-responder.js";import{EpochStaleDetector as s}from"./epoch-stale-detector.js";import{handleReceivedMessage as i}from"./receive-handler.js";import{RejoinManager as n}from"./rejoin-manager.js";import{RejoinResponder as a}from"./rejoin-responder.js";import{handleSendBroadcast as u,handleSendCommit as h}from"./send-handler.js";export class AckBatch{#e;#r;#t;#o;#s=new Set;#i=null;constructor(e){this.#e=e.flushMs,this.#r=e.flushMax,this.#t=e.send,this.#o=e.logger}add(e){let r=0===this.#s.size;if(this.#s.add(e),this.#s.size>=this.#r){null!==this.#i&&(clearTimeout(this.#i),this.#i=null),this.flush();return}r&&null===this.#i&&(this.#i=setTimeout(()=>{this.#i=null,this.flush()},this.#e))}async flush(){if(null!==this.#i&&(clearTimeout(this.#i),this.#i=null),0===this.#s.size)return;let e=Array.from(this.#s);this.#s.clear();try{await this.#t(e)}catch(r){this.#o?.error("ack batch send failed",{error:r,count:e.length})}}dispose(){null!==this.#i&&(clearTimeout(this.#i),this.#i=null),this.#s.clear()}}export function computeBackoff(e,r,t,o){let s=Math.min(r*2**e*(1+o*(2*Math.random()-1)),t);return s<0?0:s}export function abortableSleep(e,r){return new Promise((t,o)=>{if(r.aborted)return void o(r.reason??Error("aborted"));let s=setTimeout(()=>{r.removeEventListener("abort",i),t()},e),i=()=>{clearTimeout(s),r.removeEventListener("abort",i),o(r.reason??Error("aborted"))};r.addEventListener("abort",i)})}export class GroupChannel extends e{#n;#a;#u;#h;#p;#o;#c;#d;#l;#g;#m;#I=!1;constructor(e){super({dispose:async()=>{await this.#f()}}),this.#n=e.groupID,this.#a=e.deviceID,this.#u=e.hubConnection,this.#h=e.broadcastService,this.#p=e.p2pStore,this.#o=e.logger,null!=e.monitor&&(this.#c=new s({groupID:e.groupID,monitor:e.monitor})),this.#d=new a({groupID:e.groupID,exportGroupInfo:()=>this.#h.exportGroupInfo(this.#n),sendGroupInfo:(e,r)=>this.#D(e,r),logger:e.logger}),null!=e.rejoinManager?this.#l=e.rejoinManager:null!=e.monitor&&null!=e.identity&&null!=e.getRandomID&&(this.#l=new n({groupID:e.groupID,identity:e.identity,readCredential:()=>this.#h.readCredential(this.#n),genRequestID:e.getRandomID,sendRequest:e=>this.#b(e),sendCommit:e=>this.sendCommit(e),replaceHandle:e=>this.#h.replaceHandle(this.#n,e),monitor:e.monitor,logger:e.logger})),this.#g=new o({groupID:e.groupID,store:this.#p,sendCatchupReply:(e,r,t)=>this.#y(e,r,t),logger:e.logger}),null!=e.getRandomID&&(this.#m=new t({groupID:e.groupID,genRequestID:e.getRandomID,sendRequest:e=>this.#R(e),applyReply:async e=>{await this.#u.runInGroup(this.#n,()=>this.#h.applyCatchupReply(this.#n,e))},logger:e.logger}))}async open(){if(this.#I)throw Error("GroupChannel already opened");let e=await this.#p.getMLSState(this.#n,this.#a);if(null==e)throw Error(`MLS state missing for group ${this.#n}; cannot join hub group`);await this.#u.subscribe(this.#n,e.credential,e=>this.#j(e)),this.#I=!0}async #j(e){let r=await i({groupID:this.#n,message:e,broadcastService:this.#h,logger:this.#o});this.#c?.onReceiveOutcome(r.outcome,r.sequenceID);let t=r.result;if(t?.kind==="rejoin-request")this.#d.onRejoinRequest(t.requestID);else if(t?.kind==="rejoin-groupinfo")this.#d.onRejoinGroupInfoSeen(t.requestID),this.#l?.onGroupInfo(t.requestID,t.groupInfo);else if(t?.kind==="app"){let e=t.message;"circle-catchup:request"===e.type?this.#g.onCatchupRequest(e.requestID):"circle-catchup:reply"===e.type&&(this.#g.onCatchupReplySeen(e.requestID),this.#m?.onCatchupReply(e.requestID,e))}return{ack:r.ack}}async rejoinGroup(){if(null==this.#l)return{status:"recovery-failed"};let e=await this.#l.rejoin();return"recovered"===e.status&&null!=this.#m&&this.#m.run().catch(e=>{this.#o?.warn("circle catch-up after rejoin failed",{groupID:this.#n,error:e})}),e}#b(e){return this.#I?this.#h.prepareSendRejoinRequest({requestID:e,send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for rejoin request`))}#D(e,t){return this.#I?this.#h.prepareSendRejoinGroupInfo({requestID:e,groupInfo:t,send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for rejoin reply`))}#R(e){return this.#I?this.#h.prepareSend({groupID:this.#n,message:{type:"circle-catchup:request",requestID:e},send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for catch-up request`))}#y(e,t,o){return this.#I?this.#h.prepareSend({groupID:this.#n,message:{type:"circle-catchup:reply",requestID:e,circles:t,circleMembers:o},send:e=>this.#u.broadcast(this.#n,r(e))}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for catch-up reply`))}async close(){this.#I&&await this.dispose()}async #f(){if(this.#d.dispose(),this.#l?.dispose(),this.#g.dispose(),this.#m?.dispose(),this.#I){try{await this.#u.unsubscribe(this.#n)}catch(e){this.#o?.warn("hub-connection unsubscribe failed during close",{groupID:this.#n,error:e})}this.#I=!1}}broadcast(e,r){return this.#I?this.#u.runInGroup(this.#n,async()=>{if(!this.#I)throw Error(`GroupChannel for ${this.#n} is not ready for broadcast`);await u({groupID:this.#n,message:e,broadcastService:this.#h,send:(e,t)=>this.#u.broadcast(e,t,{timeoutMs:r?.timeoutMs}),logger:this.#o})},{timeoutMs:r?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for broadcast`))}sendCommit(e,r){return this.#I?this.#u.runInGroup(this.#n,async()=>{if(!this.#I)throw Error(`GroupChannel for ${this.#n} is not ready for sendCommit`);await h({groupID:this.#n,commitBytes:e,broadcastService:this.#h,send:(e,t)=>this.#u.broadcast(e,t,{timeoutMs:r?.timeoutMs}),logger:this.#o})},{timeoutMs:r?.timeoutMs}):Promise.reject(Error(`GroupChannel for ${this.#n} is not ready for sendCommit`))}}

package/lib/hub/manager.d.ts

@@ -65,16 +65,17 @@ export type UpsertHubParams = {
     serverDID?: string | null;
 };
 export declare class HubServerDIDConflictError extends Error {
-    readonly hubID: string;
-    readonly url: string;
-    readonly existingServerDID: string;
-    readonly providedServerDID: string;
+    #private;
     constructor(params: {
         hubID: string;
         url: string;
         existingServerDID: string;
         providedServerDID: string;
     });
+    get hubID(): string;
+    get url(): string;
+    get existingServerDID(): string;
+    get providedServerDID(): string;
 }
 export declare function createHub(params: CreateHubParams): Promise<Hub>;
 /**

package/lib/hub/manager.js

@@ -1 +1 @@
-import{getP2PStore as r}from"@kubun/store-p2p";export class HubServerDIDConflictError extends Error{hubID;url;existingServerDID;providedServerDID;constructor(r){super(`hub at ${r.url} is pinned to ${r.existingServerDID}; refusing to overwrite with ${r.providedServerDID}`),this.name="HubServerDIDConflictError",this.hubID=r.hubID,this.url=r.url,this.existingServerDID=r.existingServerDID,this.providedServerDID=r.providedServerDID}}function e(r){return{id:r.id,label:r.label,url:r.url,serverDID:r.server_did,createdAt:new Date(r.created_at),updatedAt:null==r.updated_at?null:new Date(r.updated_at)}}export async function createHub(t){let u=await r(t.stores),i=t.serverDID??null,a=await u.getHubByURL(t.url);if(null!=a){if(null!=a.server_did&&null!=i&&a.server_did!==i)throw new HubServerDIDConflictError({hubID:a.id,url:t.url,existingServerDID:a.server_did,providedServerDID:i});if(null==a.server_did&&null!=i){await u.updateHub(a.id,{server_did:i});let r=await u.getHub(a.id);if(null==r)throw Error("Failed to read hub after upgrade");return e(r)}return e(a)}let l=crypto.randomUUID();await u.insertHub({id:l,label:t.label??null,url:t.url,server_did:i});let n=await u.getHub(l);if(null==n)throw Error("Failed to read hub after insert");return e(n)}export async function upsertHub(r){return await createHub({stores:r.stores,url:r.url,serverDID:r.serverDID})}export async function updateHub(t){let u=await r(t.stores),i=await u.getHub(t.id);if(null==i)throw Error(`Hub ${t.id} not found`);if(null!=t.url&&t.url!==i.url){let r=await u.getHubByURL(t.url);if(null!=r&&r.id!==t.id)throw Error(`URL ${t.url} already in use by hub ${r.id}`)}let a={};void 0!==t.label&&(a.label=t.label),void 0!==t.url&&(a.url=t.url),void 0!==t.serverDID&&(a.server_did=t.serverDID),await u.updateHub(t.id,a);let l=await u.getHub(t.id);if(null==l)throw Error("Failed to read hub after update");return e(l)}export async function deleteHub(e){let t=await r(e.stores),u=await t.listGroupIDsByHubID(e.id);return u.length>0&&!e.force?{success:!1,boundGroupIDs:u}:(u.length>0&&await t.deleteGroupHubsByHubID(e.id),await t.deleteHub(e.id),{success:!0,boundGroupIDs:u})}export async function getHub(t){let u=await r(t.stores),i=await u.getHub(t.id);return null==i?null:e(i)}export async function listHubs(t){let u=await r(t.stores);return(await u.listHubs()).map(e)}export async function bindHubToGroup(e){let t=await r(e.stores);return await t.insertGroupHub({group_id:e.groupID,hub_id:e.hubID})}export async function unbindHubFromGroup(e){let t=await r(e.stores);return await t.deleteGroupHub({groupID:e.groupID,hubID:e.hubID})}export async function listHubsByGroup(t){let u=await r(t.stores);return(await u.listHubsByGroupID(t.groupID)).map(e)}export async function listGroupsByHub(e){let t=await r(e.stores);return await t.listGroupIDsByHubID(e.hubID)}export async function captureServerDID(e){let t=await r(e.stores),u=await t.getHubByURL(e.hubURL);if(null==u)return!1;if(null==u.server_did)return await t.updateHub(u.id,{server_did:e.serverDID}),!0;if(u.server_did===e.serverDID)return!1;throw new HubServerDIDConflictError({hubID:u.id,url:e.hubURL,existingServerDID:u.server_did,providedServerDID:e.serverDID})}
+import{getP2PStore as r}from"@kubun/store-p2p";export class HubServerDIDConflictError extends Error{#r;#e;#t;#u;constructor(r){super(`hub at ${r.url} is pinned to ${r.existingServerDID}; refusing to overwrite with ${r.providedServerDID}`),this.name="HubServerDIDConflictError",this.#r=r.hubID,this.#e=r.url,this.#t=r.existingServerDID,this.#u=r.providedServerDID}get hubID(){return this.#r}get url(){return this.#e}get existingServerDID(){return this.#t}get providedServerDID(){return this.#u}}function e(r){return{id:r.id,label:r.label,url:r.url,serverDID:r.server_did,createdAt:new Date(r.created_at),updatedAt:null==r.updated_at?null:new Date(r.updated_at)}}export async function createHub(t){let u=await r(t.stores),i=t.serverDID??null,a=await u.getHubByURL(t.url);if(null!=a){if(null!=a.server_did&&null!=i&&a.server_did!==i)throw new HubServerDIDConflictError({hubID:a.id,url:t.url,existingServerDID:a.server_did,providedServerDID:i});if(null==a.server_did&&null!=i){await u.updateHub(a.id,{server_did:i});let r=await u.getHub(a.id);if(null==r)throw Error("Failed to read hub after upgrade");return e(r)}return e(a)}let l=crypto.randomUUID();await u.insertHub({id:l,label:t.label??null,url:t.url,server_did:i});let n=await u.getHub(l);if(null==n)throw Error("Failed to read hub after insert");return e(n)}export async function upsertHub(r){return await createHub({stores:r.stores,url:r.url,serverDID:r.serverDID})}export async function updateHub(t){let u=await r(t.stores),i=await u.getHub(t.id);if(null==i)throw Error(`Hub ${t.id} not found`);if(null!=t.url&&t.url!==i.url){let r=await u.getHubByURL(t.url);if(null!=r&&r.id!==t.id)throw Error(`URL ${t.url} already in use by hub ${r.id}`)}let a={};void 0!==t.label&&(a.label=t.label),void 0!==t.url&&(a.url=t.url),void 0!==t.serverDID&&(a.server_did=t.serverDID),await u.updateHub(t.id,a);let l=await u.getHub(t.id);if(null==l)throw Error("Failed to read hub after update");return e(l)}export async function deleteHub(e){let t=await r(e.stores),u=await t.listGroupIDsByHubID(e.id);return u.length>0&&!e.force?{success:!1,boundGroupIDs:u}:(u.length>0&&await t.deleteGroupHubsByHubID(e.id),await t.deleteHub(e.id),{success:!0,boundGroupIDs:u})}export async function getHub(t){let u=await r(t.stores),i=await u.getHub(t.id);return null==i?null:e(i)}export async function listHubs(t){let u=await r(t.stores);return(await u.listHubs()).map(e)}export async function bindHubToGroup(e){let t=await r(e.stores);return await t.insertGroupHub({group_id:e.groupID,hub_id:e.hubID})}export async function unbindHubFromGroup(e){let t=await r(e.stores);return await t.deleteGroupHub({groupID:e.groupID,hubID:e.hubID})}export async function listHubsByGroup(t){let u=await r(t.stores);return(await u.listHubsByGroupID(t.groupID)).map(e)}export async function listGroupsByHub(e){let t=await r(e.stores);return await t.listGroupIDsByHubID(e.hubID)}export async function captureServerDID(e){let t=await r(e.stores),u=await t.getHubByURL(e.hubURL);if(null==u)return!1;if(null==u.server_did)return await t.updateHub(u.id,{server_did:e.serverDID}),!0;if(u.server_did===e.serverDID)return!1;throw new HubServerDIDConflictError({hubID:u.id,url:e.hubURL,existingServerDID:u.server_did,providedServerDID:e.serverDID})}

package/lib/hub/receive-handler.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '@kubun/logger';
-import { type BroadcastService } from '../groups/broadcast-service.js';
+import { type BroadcastService, type ReceiveBroadcastResult } from '../groups/broadcast-service.js';
 /**
  * Shape of a message pushed by `hub/receive`. Matches `@enkaku/hub-protocol`
  * server-to-client push payload.
@@ -17,8 +17,26 @@ export type HandleReceivedMessageParams = {
     broadcastService: BroadcastService;
     logger?: Logger;
 };
+/**
+ * Classification of a single received message's processing result. Drives both
+ * the ack decision and the epoch-stale health signal (see `EpochStaleDetector`):
+ * - `applied` — decrypted/applied cleanly; the device is at the current epoch.
+ * - `decrypt-failed` — could not derive the key for the current epoch.
+ * - `commit-out-of-order` — a Commit ahead of the local epoch (gap in stream).
+ * - `apply-failed` — decrypted but failed to apply to the local DB (transient).
+ * - `error` — unexpected failure.
+ * - `skipped` — not for this group; no processing attempted.
+ * - `control` — a rejoin control frame (request/groupinfo); processed cleanly
+ *   but NOT a health indicator (must not reset epoch-stale tracking).
+ */
+export type ReceiveOutcome = 'applied' | 'decrypt-failed' | 'commit-out-of-order' | 'apply-failed' | 'error' | 'skipped' | 'control';
 export type HandleReceivedMessageResult = {
     ack: boolean;
+    outcome: ReceiveOutcome;
+    sequenceID: string;
+    /** The processed result, present on success — lets the channel route rejoin
+     *  control frames to the responder/requester. */
+    result?: ReceiveBroadcastResult;
 };
 /**
  * Apply a single hub-received message for a group.
@@ -28,6 +46,6 @@ export type HandleReceivedMessageResult = {
  * no recovery path). Returns `{ ack: false }` when the hub should redeliver
  * (transient apply failure or unexpected error). Skips with `{ ack: false }`
  * on groupID mismatch so the message stays queued for whichever recipient it
- * was intended for.
+ * was intended for. The `outcome` classifies the result for health tracking.
  */
 export declare function handleReceivedMessage(params: HandleReceivedMessageParams): Promise<HandleReceivedMessageResult>;

package/lib/hub/receive-handler.js

@@ -1 +1 @@
-import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,CommitOutOfOrderError as c,DecryptError as s}from"../groups/broadcast-service.js";export async function handleReceivedMessage(a){let{groupID:n,message:o,broadcastService:i,logger:t}=a;if(o.groupID!==n)return t?.debug("hub message groupID mismatch, skipping",{groupID:n,messageGroupID:o.groupID,sequenceID:o.sequenceID}),{ack:!1};let u=e(o.payload);try{await i.processReceived({groupID:n,encrypted:u})}catch(e){if(e instanceof s)return t?.debug("decrypt failed, acking and skipping",{groupID:n,sequenceID:o.sequenceID,error:e}),{ack:!0};if(e instanceof c)return t?.debug("mls commit out of order, will redeliver after gap fills",{groupID:n,sequenceID:o.sequenceID,messageEpoch:e.messageEpoch.toString(),handleEpoch:e.handleEpoch.toString()}),{ack:!1};if(e instanceof r)return t?.error("broadcast apply failed, will redeliver",{groupID:n,sequenceID:o.sequenceID,error:e}),{ack:!1};return t?.error("unexpected error processing hub message",{groupID:n,sequenceID:o.sequenceID,error:e}),{ack:!1}}return{ack:!0}}
+import{fromB64 as e}from"@enkaku/codec";import{ApplyError as r,CommitOutOfOrderError as o,DecryptError as a,MalformedControlError as c}from"../groups/broadcast-service.js";export async function handleReceivedMessage(i){let t,{groupID:n,message:s,broadcastService:p,logger:u}=i,d=s.sequenceID;if(s.groupID!==n)return u?.debug("hub message groupID mismatch, skipping",{groupID:n,messageGroupID:s.groupID,sequenceID:d}),{ack:!1,outcome:"skipped",sequenceID:d};let l=e(s.payload);try{t=await p.processReceived({groupID:n,encrypted:l})}catch(e){if(e instanceof c)return u?.debug("malformed control frame, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"control",sequenceID:d};if(e instanceof a)return u?.debug("decrypt failed, acking and skipping",{groupID:n,sequenceID:d,error:e}),{ack:!0,outcome:"decrypt-failed",sequenceID:d};if(e instanceof o)return u?.debug("mls commit out of order, will redeliver after gap fills",{groupID:n,sequenceID:d,messageEpoch:e.messageEpoch.toString(),handleEpoch:e.handleEpoch.toString()}),{ack:!1,outcome:"commit-out-of-order",sequenceID:d};if(e instanceof r)return u?.error("broadcast apply failed, will redeliver",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"apply-failed",sequenceID:d};return u?.error("unexpected error processing hub message",{groupID:n,sequenceID:d,error:e}),{ack:!1,outcome:"error",sequenceID:d}}return{ack:!0,outcome:"rejoin-request"===t.kind||"rejoin-groupinfo"===t.kind?"control":"applied",sequenceID:d,result:t}}

package/lib/hub/rejoin-manager.d.ts

@@ -0,0 +1,78 @@
+import { type GroupHandle, type MemberCredential } from '@enkaku/group';
+import type { OwnIdentity } from '@enkaku/token';
+import type { Logger } from '@kubun/logger';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.js';
+export type JoinExternalResult = {
+    /** Framed MLSMessage(Commit) bytes to broadcast to existing members. */
+    commitMessage: Uint8Array;
+    /** Optimistic post-commit handle (NOT yet persisted). */
+    pendingHandle: GroupHandle;
+};
+export type RejoinManagerParams = {
+    groupID: string;
+    identity: OwnIdentity;
+    /** Read the stale handle's cached MemberCredential (reused for the rejoin). */
+    readCredential: () => Promise<MemberCredential>;
+    /** Fresh correlation id per request (incl. retries). */
+    genRequestID: () => string;
+    /** Broadcast a `rejoin-request` on the group channel. */
+    sendRequest: (requestID: string) => Promise<void>;
+    /** Broadcast the resync Commit (`mls` frame) to existing members. */
+    sendCommit: (commitBytes: Uint8Array) => Promise<void>;
+    /** Atomically swap the cached handle for the confirmed one (registry). */
+    replaceHandle: (handle: GroupHandle) => Promise<void>;
+    monitor: GroupHealthMonitor;
+    /**
+     * Test seam: defaults to `@enkaku/group` `joinGroupExternal({resync:true})`
+     * built from `identity` + `readCredential`. Override to skip real MLS.
+     */
+    joinExternal?: (groupInfo: Uint8Array) => Promise<JoinExternalResult>;
+    /** Test seam: defaults to `@enkaku/group` `inspectGroupInfo`. */
+    inspectGroupInfo?: (groupInfo: Uint8Array) => {
+        epoch: bigint;
+        treeHash: Uint8Array;
+    };
+    requestTimeoutMs?: number;
+    confirmTimeoutMs?: number;
+    /** Delay between the candidate-head probe and its re-probe (settle window). */
+    confirmSettleMs?: number;
+    maxAttempts?: number;
+    backoffMs?: (attempt: number) => number;
+    logger?: Logger;
+};
+/**
+ * Drives a stale device's MLS epoch recovery for one group: per attempt,
+ * request GroupInfo → `joinGroupExternal({resync:true})` → broadcast the resync
+ * Commit → confirm → `replaceHandle`.
+ *
+ * Confirm is a tree-hash compare against the current head, because the hub never
+ * echoes the sender's own Commit. Three guards keep it reliable under concurrent
+ * rejoins (a resync Commit is canonical only for an instant):
+ * - behind-responder filter: a probe reply below our epoch can't confirm us.
+ * - chase-the-head: a reply above our epoch means we lost the race; re-join the
+ *   newer GroupInfo next attempt (`{resync:true}` rebuilds the tree — no replay).
+ * - settle re-probe: re-probe after a delay and require the head still ours
+ *   before swapping. Shrinks (not closes) the transient-head window — a Commit
+ *   landing in the gap leaves us one epoch behind, which detect→rejoin catches.
+ *   A fall-behind, never a silent fork; a wrong `recovered` is unreachable.
+ *
+ * Retries capped; exhaustion → `recovery-failed`.
+ */
+export declare class RejoinManager {
+    #private;
+    constructor(params: RejoinManagerParams);
+    get inFlight(): boolean;
+    /**
+     * Route a received `rejoin-groupinfo`: resolve the matching in-flight waiter.
+     * Unknown `requestID`s (peers' requests, stale responses) are ignored.
+     */
+    onGroupInfo(requestID: string, groupInfo: Uint8Array): void;
+    /** Run the recovery flow. Idempotent: a concurrent call returns the loser early. */
+    rejoin(): Promise<RejoinResult>;
+    /**
+     * Stop a running rejoin and release timers. Idempotent; the loop checks
+     * `#disposed` between attempts, pending waiters resolve `null`. On channel close.
+     */
+    dispose(): void;
+}

package/lib/hub/rejoin-manager.js

@@ -0,0 +1 @@
+import{inspectGroupInfo as e,joinGroupExternal as t}from"@enkaku/group";import{bytesEqual as r,sleep as i,unref as s}from"../utils.js";export class RejoinManager{#e;#t;#r;#i;#s;#o;#n;#a;#l;#u;#h;#c;#p;#m;#d=new Map;#f=!1;#g=!1;constructor(r){this.#e=r.groupID,this.#t=r.genRequestID,this.#r=r.sendRequest,this.#i=r.sendCommit,this.#s=r.replaceHandle,this.#o=r.monitor,this.#n=r.joinExternal??(async e=>{let i=await r.readCredential(),{commitMessage:s,group:o}=await t({identity:r.identity,groupInfo:e,credential:i,resync:!0});return{commitMessage:s,pendingHandle:o}}),this.#a=r.inspectGroupInfo??e,this.#l=r.requestTimeoutMs??5e3,this.#u=r.confirmTimeoutMs??5e3,this.#h=r.confirmSettleMs??300,this.#c=r.maxAttempts??8,this.#p=r.backoffMs??o,this.#m=r.logger}get inFlight(){return this.#f}onGroupInfo(e,t){let r=this.#d.get(e);null!=r&&(this.#d.delete(e),r.resolve(t))}async rejoin(){if(this.#f)return{status:"recovery-failed"};this.#f=!0,this.#o.markRecovering(this.#e);try{for(let e=0;e<this.#c&&!this.#g&&(await i(this.#p(e)),!this.#g);e++){let e=await this.#w();if("recovered"===e)return this.#o.markRecovered(this.#e),{status:"recovered"}}return this.#o.markRecoveryFailed(this.#e),{status:"recovery-failed"}}finally{this.#f=!1}}async #w(){let e,t=await this.#I(this.#l);if(null==t)return"retry";try{e=await this.#n(t)}catch(e){return this.#m?.warn("rejoin: joinGroupExternal failed",{groupID:this.#e,error:e}),"retry"}let{commitMessage:s,pendingHandle:o}=e,n=o.epoch,a=o.treeHash;try{await this.#i(s)}catch(e){return this.#m?.warn("rejoin: resync Commit send failed",{groupID:this.#e,error:e}),"retry"}let l=await this.#y(n);if(null==l||!(l.epoch===n&&r(l.treeHash,a)))return"retry";await i(this.#h);let u=await this.#y(n);return null==u?"retry":u.epoch===n&&r(u.treeHash,a)?(await this.#s(o),"recovered"):"retry"}async #y(e){let t,r=await this.#I(this.#u);if(null==r)return null;try{t=this.#a(r)}catch(e){return this.#m?.warn("rejoin: confirm GroupInfo inspect failed",{groupID:this.#e,error:e}),null}return t.epoch<e?null:t}async #I(e){let t=this.#t(),r=this.#M(t,e);try{await this.#r(t)}catch(e){return this.#D(t),this.#m?.warn("rejoin: request send failed",{groupID:this.#e,error:e}),null}return r}#M(e,t){return new Promise(r=>{let i=setTimeout(()=>{this.#d.delete(e),r(null)},t);s(i),this.#d.set(e,{resolve:e=>{clearTimeout(i),r(e)},cancel:()=>{clearTimeout(i),r(null)}})})}#D(e){this.#d.delete(e)}dispose(){for(let e of(this.#g=!0,this.#d.values()))e.cancel();this.#d.clear()}}function o(e){return Math.floor(Math.random()*Math.min(500*2**(e-1),5e3))}

package/lib/hub/rejoin-responder.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from '@kubun/logger';
+export type RejoinResponderParams = {
+    groupID: string;
+    /** Produce a fresh GroupInfo for this group (current MLS handle). */
+    exportGroupInfo: () => Promise<Uint8Array>;
+    /** Broadcast a `rejoin-groupinfo` reply to the group channel. */
+    sendGroupInfo: (requestID: string, groupInfo: Uint8Array) => Promise<void>;
+    /** Jitter delay (ms) before replying. Defaults to a random 0..250ms. */
+    nextJitterMs?: () => number;
+    /** How long a `requestID` stays suppressed after being answered. */
+    suppressTTLMs?: number;
+    logger?: Logger;
+};
+/**
+ * Answers `rejoin-request`s with a fresh GroupInfo. Every member could reply, so
+ * jitter (random pre-reply delay) + suppression (cancel on seeing a peer's reply
+ * for the same `requestID`) collapse the storm to ~1 reply. Keyed on `requestID`
+ * (fresh per attempt); suppression entries TTL out to bound memory.
+ *
+ * Suppression collapses only duplicates of one `requestID`, so distinct
+ * `requestID`s still draw one reply each — an amplification. A per-window reply
+ * cap is tracked in `docs/agents/plans/backlog/rejoin-frame-authentication.md`.
+ */
+export declare class RejoinResponder {
+    #private;
+    constructor(params: RejoinResponderParams);
+    /** Handle an inbound `rejoin-request`: schedule a jittered, suppressible reply. */
+    onRejoinRequest(requestID: string): void;
+    /** Handle an observed `rejoin-groupinfo` (own or peer's): suppress this request. */
+    onRejoinGroupInfoSeen(requestID: string): void;
+    dispose(): void;
+}

package/lib/hub/rejoin-responder.js

@@ -0,0 +1 @@
+import{unref as e}from"../utils.js";export class RejoinResponder{#e;#s;#t;#r;#p;#o;#i=new Map;#n=new Map;constructor(e){this.#e=e.groupID,this.#s=e.exportGroupInfo,this.#t=e.sendGroupInfo,this.#r=e.nextJitterMs??(()=>Math.floor(250*Math.random())),this.#p=e.suppressTTLMs??5e3,this.#o=e.logger}onRejoinRequest(s){if(this.#n.has(s)||this.#i.has(s))return;let t=setTimeout(()=>{this.#i.delete(s),this.#u(s)},this.#r());e(t),this.#i.set(s,t)}onRejoinGroupInfoSeen(e){let s=this.#i.get(e);null!=s&&(clearTimeout(s),this.#i.delete(e)),this.#h(e)}dispose(){for(let e of this.#i.values())clearTimeout(e);for(let e of(this.#i.clear(),this.#n.values()))clearTimeout(e);this.#n.clear()}async #u(e){if(!this.#n.has(e)){this.#h(e);try{let s=await this.#s();await this.#t(e,s)}catch(s){this.#o?.warn("rejoin responder failed to reply",{groupID:this.#e,requestID:e,error:s})}}}#h(s){let t=this.#n.get(s);null!=t&&clearTimeout(t);let r=setTimeout(()=>{this.#n.delete(s)},this.#p);e(r),this.#n.set(s,r)}}

package/lib/hub/relay-manager.d.ts

@@ -1,10 +1,13 @@
 import type { Client } from '@enkaku/client';
 import { EventEmitter } from '@enkaku/event';
 import type { HubProtocol } from '@enkaku/hub-protocol';
+import type { OwnIdentity } from '@enkaku/token';
 import type { Logger } from '@kubun/logger';
 import type { P2PStoreAPI } from '@kubun/store-p2p';
 import type { GroupBroadcastMessage } from '../groups/broadcast.js';
 import type { BroadcastService } from '../groups/broadcast-service.js';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
+import type { RejoinResult } from '../types.js';
 import { type OnServerDIDObserved } from './connection-pool.js';
 import type { ServerDIDMismatchObserver, ServerDIDObserver } from './did-observing-transport.js';
 import { GroupChannel, type GroupChannelParams } from './group-channel.js';
@@ -72,6 +75,12 @@ export type HubRelayManagerParams = {
     backoffMaxMs?: number;
     backoffJitter?: number;
     broadcastTimeoutMs?: number;
+    /** When provided, receive outcomes drive epoch-stale health detection. */
+    monitor?: GroupHealthMonitor;
+    /** Device identity — enables the rejoin flow (needs `joinGroupExternal`). */
+    identity?: OwnIdentity;
+    /** Fresh correlation ids for rejoin requests. */
+    getRandomID?: () => string;
     createGroupChannel?: CreateGroupChannel;
     createHubConnection?: CreateHubConnection;
     /**
@@ -85,7 +94,7 @@ export type HubRelayManagerParams = {
 };
 export declare class HubRelayManager {
     #private;
-    readonly relayEvents: EventEmitter<RelayManagerEvents>;
+    get relayEvents(): EventEmitter<RelayManagerEvents>;
     constructor(params: HubRelayManagerParams);
     /**
      * Open channels for each group in parallel. Per-group failures are logged
@@ -112,6 +121,12 @@ export declare class HubRelayManager {
      */
     removeBinding(groupID: string, hubURL: string): Promise<void>;
     removeGroup(groupID: string): Promise<void>;
+    /**
+     * Run stale-device MLS epoch recovery for an active group via its channel.
+     * Throws if the group is not active; returns `recovery-failed` if the rejoin
+     * flow is unavailable (no monitor/identity wired).
+     */
+    rejoinGroup(groupID: string): Promise<RejoinResult>;
     broadcast(groupID: string, message: GroupBroadcastMessage, opts?: {
         timeoutMs?: number;
     }): Promise<void>;

package/lib/hub/relay-manager.js

@@ -1 +1 @@
-import{EventEmitter as e}from"@enkaku/event";import{HubConnectionPool as t}from"./connection-pool.js";import{GroupChannel as s}from"./group-channel.js";import{HubConnection as r}from"./hub-connection.js";export class HubRelayManager{#e;#t;#s;#r;#o;#a;#i;#n;#l;#c;#u;#h;#p;#g=new Map;#d=new Map;#b=new Map;#f=new Map;relayEvents;constructor(o){this.#e=o.p2pStore,this.#t=o.broadcastService,this.#s=o.deviceID,this.#o=o.logger,this.#a=o.ackFlushMs??500,this.#i=o.ackFlushMax??10,this.#n=o.backoffBaseMs??1e3,this.#l=o.backoffMaxMs??6e4,this.#c=o.backoffJitter??.25,this.#u=o.broadcastTimeoutMs;let a=o.p2pStore;this.#r=new t({createHubClient:o.createHubClient,logger:o.logger,onServerDIDObserved:o.onServerDIDObserved,resolvePinnedDID:async e=>{let t=await a.getHubByURL(e);return t?.server_did??null}}),this.#h=o.createGroupChannel??(e=>new s(e)),this.#p=o.createHubConnection??(e=>new r(e)),this.relayEvents=new e}async #M(e){let t=this.#g.get(e);if(null!=t)return t;let s=this.#p({hubURL:e,deviceID:this.#s,pool:this.#r,logger:this.#o,ackFlushMs:this.#a,ackFlushMax:this.#i,backoffBaseMs:this.#n,backoffMaxMs:this.#l,backoffJitter:this.#c});try{await s.open()}catch(e){try{await s.dispose()}catch{}throw e}let r=s.events.on("lifecycle",async t=>{let s=Object.freeze([...this.#b.entries()].filter(([,t])=>t===e).map(([e])=>e));await this.relayEvents.emit("relay",{...t,hubURL:e,groupIDs:s})});return this.#f.set(e,r),this.#g.set(e,s),s}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((t,s)=>{"rejected"===t.status&&this.#o?.error("addGroup failed during start",{groupID:e[s],error:t.reason})})}async addGroup(e){if(this.#d.has(e))return void this.#o?.debug("group already added",{groupID:e});if(null==await this.#e.getGroup(e))throw Error(`Group ${e} not found`);let t=await this.#e.listHubsByGroupID(e);0===t.length?this.#o?.warn("group has no hub bindings, skipping",{groupID:e}):(t.length>1&&this.#o?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t.map(e=>e.url)}),await this.#m(e,t[0].url))}async #m(e,t){let s=await this.#M(t),r=this.#h({groupID:e,deviceID:this.#s,hubConnection:s,broadcastService:this.#t,p2pStore:this.#e,logger:this.#o});await r.open(),this.#d.set(e,r),this.#b.set(e,t)}async addBinding(e,t){let s=this.#b.get(e);null!=s?s===t?this.#o?.debug("binding already active",{groupID:e,hubURL:t}):this.#o?.warn("multi-hub not yet supported, ignoring extra binding",{groupID:e,activeHubURL:s,newHubURL:t}):await this.#m(e,t)}async removeBinding(e,t){this.#b.get(e)!==t?this.#o?.debug("binding not active, ignoring removal",{groupID:e,hubURL:t}):await this.removeGroup(e)}async removeGroup(e){let t=this.#d.get(e);null!=t&&(await t.close(),this.#d.delete(e),this.#b.delete(e))}async broadcast(e,t,s){let r=this.#d.get(e);if(null==r)throw Error(`Group ${e} is not active in HubRelayManager`);let o=s?.timeoutMs??this.#u;await r.broadcast(t,{timeoutMs:o})}async sendCommit(e,t,s){let r=this.#d.get(e);if(null==r)throw Error(`Group ${e} is not active in HubRelayManager`);let o=s?.timeoutMs??this.#u;await r.sendCommit(t,{timeoutMs:o})}async stop(){for(let e of this.#f.values())e();this.#f.clear();let e=[...this.#d.values()];this.#d.clear(),this.#b.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("GroupChannel close failed",{error:e.reason})});let t=[...this.#g.values()];this.#g.clear(),(await Promise.allSettled(t.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#o?.warn("HubConnection close failed",{error:e.reason})}),await this.#r.disposeAll()}}
+import{EventEmitter as e}from"@enkaku/event";import{HubConnectionPool as t}from"./connection-pool.js";import{GroupChannel as s}from"./group-channel.js";import{HubConnection as o}from"./hub-connection.js";export class HubRelayManager{#e;#t;#s;#o;#r;#i;#a;#n;#l;#c;#u;#h;#g;#p;#d;#b;#f=new Map;#m=new Map;#M=new Map;#v=new Map;#w;get relayEvents(){return this.#w}constructor(r){this.#e=r.p2pStore,this.#t=r.broadcastService,this.#s=r.deviceID,this.#r=r.logger,this.#i=r.ackFlushMs??500,this.#a=r.ackFlushMax??10,this.#n=r.backoffBaseMs??1e3,this.#l=r.backoffMaxMs??6e4,this.#c=r.backoffJitter??.25,this.#u=r.broadcastTimeoutMs,this.#h=r.monitor,this.#g=r.identity,this.#p=r.getRandomID;let i=r.p2pStore;this.#o=new t({createHubClient:r.createHubClient,logger:r.logger,onServerDIDObserved:r.onServerDIDObserved,resolvePinnedDID:async e=>{let t=await i.getHubByURL(e);return t?.server_did??null}}),this.#d=r.createGroupChannel??(e=>new s(e)),this.#b=r.createHubConnection??(e=>new o(e)),this.#w=new e}async #y(e){let t=this.#f.get(e);if(null!=t)return t;let s=this.#b({hubURL:e,deviceID:this.#s,pool:this.#o,logger:this.#r,ackFlushMs:this.#i,ackFlushMax:this.#a,backoffBaseMs:this.#n,backoffMaxMs:this.#l,backoffJitter:this.#c});try{await s.open()}catch(e){try{await s.dispose()}catch{}throw e}let o=s.events.on("lifecycle",async t=>{let s=Object.freeze([...this.#M.entries()].filter(([,t])=>t===e).map(([e])=>e));await this.#w.emit("relay",{...t,hubURL:e,groupIDs:s})});return this.#v.set(e,o),this.#f.set(e,s),s}async start(e){(await Promise.allSettled(e.map(e=>this.addGroup(e)))).forEach((t,s)=>{"rejected"===t.status&&this.#r?.error("addGroup failed during start",{groupID:e[s],error:t.reason})})}async addGroup(e){if(this.#m.has(e))return void this.#r?.debug("group already added",{groupID:e});if(null==await this.#e.getGroup(e))throw Error(`Group ${e} not found`);let t=await this.#e.listHubsByGroupID(e);0===t.length?this.#r?.warn("group has no hub bindings, skipping",{groupID:e}):(t.length>1&&this.#r?.warn("multi-hub not yet supported, using first",{groupID:e,hubURLs:t.map(e=>e.url)}),await this.#k(e,t[0].url))}async #k(e,t){let s=await this.#y(t),o=this.#d({groupID:e,deviceID:this.#s,hubConnection:s,broadcastService:this.#t,p2pStore:this.#e,logger:this.#r,monitor:this.#h,identity:this.#g,getRandomID:this.#p});await o.open(),this.#m.set(e,o),this.#M.set(e,t)}async addBinding(e,t){let s=this.#M.get(e);null!=s?s===t?this.#r?.debug("binding already active",{groupID:e,hubURL:t}):this.#r?.warn("multi-hub not yet supported, ignoring extra binding",{groupID:e,activeHubURL:s,newHubURL:t}):await this.#k(e,t)}async removeBinding(e,t){this.#M.get(e)!==t?this.#r?.debug("binding not active, ignoring removal",{groupID:e,hubURL:t}):await this.removeGroup(e)}async removeGroup(e){let t=this.#m.get(e);null!=t&&(await t.close(),this.#m.delete(e),this.#M.delete(e))}async rejoinGroup(e){let t=this.#m.get(e);if(null==t)throw Error(`Group ${e} is not active in HubRelayManager`);return await t.rejoinGroup()}async broadcast(e,t,s){let o=this.#m.get(e);if(null==o)throw Error(`Group ${e} is not active in HubRelayManager`);let r=s?.timeoutMs??this.#u;await o.broadcast(t,{timeoutMs:r})}async sendCommit(e,t,s){let o=this.#m.get(e);if(null==o)throw Error(`Group ${e} is not active in HubRelayManager`);let r=s?.timeoutMs??this.#u;await o.sendCommit(t,{timeoutMs:r})}async stop(){for(let e of this.#v.values())e();this.#v.clear();let e=[...this.#m.values()];this.#m.clear(),this.#M.clear(),(await Promise.allSettled(e.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#r?.warn("GroupChannel close failed",{error:e.reason})});let t=[...this.#f.values()];this.#f.clear(),(await Promise.allSettled(t.map(e=>e.close()))).forEach(e=>{"rejected"===e.status&&this.#r?.warn("HubConnection close failed",{error:e.reason})}),await this.#o.disposeAll()}}

package/lib/hub/wiring.d.ts

@@ -1,13 +1,15 @@
 import type { OwnIdentity } from '@enkaku/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 { GroupBroadcastMessage } from '../groups/broadcast.js';
 import { type BroadcastEvent } from '../groups/broadcast-service.js';
 import type { P2PEventEmitter } from '../groups/events.js';
 import type { GroupHandleRegistry } from '../groups/group-handle-registry.js';
+import type { GroupHealthMonitor } from '../groups/group-health-monitor.js';
 import type { ForwardingConfig } from '../sync/forwarder.js';
-import type { StoreUnreadableMode } from '../types.js';
+import type { RejoinResult, StoreUnreadableMode } from '../types.js';
 import type { OnServerDIDObserved } from './connection-pool.js';
 import type { GroupChannel, GroupChannelParams } from './group-channel.js';
 import type { HubConnection, HubConnectionParams } from './hub-connection.js';
@@ -27,10 +29,18 @@ export type HubWiring = {
      * group's existing members. Wired to `HubRelayManager.sendCommit`.
      */
     scheduleSendCommit: (groupID: string, commitBytes: Uint8Array) => void;
+    /**
+     * Run stale-device MLS epoch recovery for an active group. Wired to
+     * `HubRelayManager.rejoinGroup`; a no-op `recovery-failed` under
+     * `DISABLED_HUB` (no relay, nothing to rejoin).
+     */
+    rejoinGroup: (groupID: string) => Promise<RejoinResult>;
     dispose: () => Promise<void>;
 };
 export type SetupHubRelayParams = {
     identity: OwnIdentity;
+    /** Fresh correlation ids for the rejoin flow. */
+    getRandomID: () => string;
     db: KubunDB;
     /**
      * Engine graph internals — threaded through to `BroadcastService` so the
@@ -47,6 +57,8 @@ export type SetupHubRelayParams = {
      * mutex once Phase 3 lands. Currently stored but unused.
      */
     registry: GroupHandleRegistry;
+    /** Shared health monitor; receive outcomes drive epoch-stale detection. */
+    monitor?: GroupHealthMonitor;
     logger: Logger;
     /**
      * Optional testing seam forwarded to `HubRelayManager`. Production code
@@ -80,6 +92,12 @@ export type SetupHubRelayParams = {
      * pinning; omitting it skips capture entirely.
      */
     onServerDIDObserved?: OnServerDIDObserved;
+    /**
+     * Device-wide monotonic clock forwarded to `BroadcastService` for stamping
+     * `removed_at_hlc` on roster reconciliation. Required: production passes the
+     * engine's single instance so roster writes share the device's one clock.
+     */
+    hlc: HLC;
 };
 export declare function setupHubRelay(params: SetupHubRelayParams): HubWiring;
 export declare const DISABLED_HUB: HubWiring;

package/lib/hub/wiring.js

@@ -1 +1 @@
-import{HLC as e}from"@kubun/hlc";import{BroadcastService as r}from"../groups/broadcast-service.js";import{HubRelayManager as o}from"./relay-manager.js";export function setupHubRelay(a){let t,{identity:d,db:i,graph:n,emitter:s,createHubClient:c,onRemoteBroadcast:u,registry:p,logger:h,createGroupChannel:l,createHubConnection:m,storeUnreadable:g,defaultAccessLevel:f,forwarding:b,onServerDIDObserved:y}=a,w=[],D=(e,r)=>{t.then(o=>o.broadcast(e,r).catch(r=>{h.error("broadcast failed",{groupID:e,error:r})}),()=>{})},v=async(e,r)=>{let o=await t;await o.broadcast(e,r)};return(t=(async()=>{let[a,t]=await Promise.all([i.getStore("p2p"),i.getStore("graph")]),v=new r({p2pStore:a,graphStore:t,graph:n,selfDID:d.id,registry:p,hlc:new e({nodeID:d.id}),storeUnreadable:g,defaultAccessLevel:f,forwarding:b,scheduleBroadcast:D,emitter:s,logger:h}),B=new o({p2pStore:a,broadcastService:v,deviceID:d.id,createHubClient:c,logger:h,createGroupChannel:l,createHubConnection:m,onServerDIDObserved:y});w.push(v.on("broadcast",u)),w.push(s.on("groupJoined",e=>B.addGroup(e.id).catch(r=>{h.error("addGroup failed",{groupID:e.id,error:r})}))),w.push(s.on("groupLeft",e=>B.removeGroup(e.groupID).catch(r=>{h.error("removeGroup failed",{groupID:e.groupID,error:r})}))),w.push(s.on("hubBound",({groupID:e,hubURL:r})=>B.addBinding(e,r).catch(o=>{h.error("addBinding failed",{groupID:e,hubURL:r,error:o})}))),w.push(s.on("hubUnbound",({groupID:e,hubURL:r})=>B.removeBinding(e,r).catch(o=>{h.error("removeBinding failed",{groupID:e,hubURL:r,error:o})})));let I=await a.listGroups();return await B.start(I.map(e=>e.id)),B})()).catch(e=>{h.error("hub relay setup failed",{error:e})}),{ready:t.then(()=>void 0),scheduleBroadcast:D,broadcastNow:v,scheduleSendCommit:(e,r)=>{t.then(o=>o.sendCommit(e,r).catch(r=>{h.error("sendCommit failed",{groupID:e,error:r})}),()=>{})},dispose:async()=>{for(let e of w)try{e()}catch{}w.length=0;try{let e=await t;await e.stop()}catch{}}}}export const DISABLED_HUB={ready:Promise.resolve(),scheduleBroadcast:()=>{},broadcastNow:async()=>{},scheduleSendCommit:()=>{},dispose:async()=>{}};
+import{BroadcastService as e}from"../groups/broadcast-service.js";import{HubRelayManager as r}from"./relay-manager.js";export function setupHubRelay(a){let o,{identity:t,getRandomID:d,db:i,graph:s,emitter:n,createHubClient:c,onRemoteBroadcast:u,registry:p,monitor:l,logger:h,createGroupChannel:m,createHubConnection:g,storeUnreadable:f,defaultAccessLevel:y,forwarding:w,onServerDIDObserved:b,hlc:v}=a,D=[],B=(e,r)=>{o.then(a=>a.broadcast(e,r).catch(r=>{h.error("broadcast failed",{groupID:e,error:r})}),()=>{})},G=async(e,r)=>{let a=await o;await a.broadcast(e,r)},I=async e=>{let r=await o;return await r.rejoinGroup(e)};return(o=(async()=>{let[a,o]=await Promise.all([i.getStore("p2p"),i.getStore("graph")]),G=new e({p2pStore:a,graphStore:o,graph:s,selfDID:t.id,registry:p,hlc:v,storeUnreadable:f,defaultAccessLevel:y,forwarding:w,scheduleBroadcast:B,emitter:n,logger:h}),I=new r({p2pStore:a,broadcastService:G,deviceID:t.id,createHubClient:c,monitor:l,identity:t,getRandomID:d,logger:h,createGroupChannel:m,createHubConnection:g,onServerDIDObserved:b});D.push(G.on("broadcast",u)),D.push(n.on("groupJoined",e=>I.addGroup(e.id).catch(r=>{h.error("addGroup failed",{groupID:e.id,error:r})}))),D.push(n.on("groupLeft",e=>I.removeGroup(e.groupID).catch(r=>{h.error("removeGroup failed",{groupID:e.groupID,error:r})}))),D.push(n.on("hubBound",({groupID:e,hubURL:r})=>I.addBinding(e,r).catch(a=>{h.error("addBinding failed",{groupID:e,hubURL:r,error:a})}))),D.push(n.on("hubUnbound",({groupID:e,hubURL:r})=>I.removeBinding(e,r).catch(a=>{h.error("removeBinding failed",{groupID:e,hubURL:r,error:a})})));let S=await a.listGroups();return await I.start(S.map(e=>e.id)),I})()).catch(e=>{h.error("hub relay setup failed",{error:e})}),{ready:o.then(()=>void 0),scheduleBroadcast:B,broadcastNow:G,scheduleSendCommit:(e,r)=>{o.then(a=>a.sendCommit(e,r).catch(r=>{h.error("sendCommit failed",{groupID:e,error:r})}),()=>{})},rejoinGroup:I,dispose:async()=>{for(let e of D)try{e()}catch{}D.length=0;try{let e=await o;await e.stop()}catch{}}}}export const DISABLED_HUB={ready:Promise.resolve(),scheduleBroadcast:()=>{},broadcastNow:async()=>{},scheduleSendCommit:()=>{},rejoinGroup:async()=>({status:"recovery-failed"}),dispose:async()=>{}};