@kubun/plugin-p2p 0.10.1 → 0.12.0

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

@@ -1,58 +0,0 @@
-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

@@ -1 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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

@@ -1 +0,0 @@
-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/connection-pool.d.ts

@@ -1,43 +0,0 @@
-import type { Client } from '@enkaku/client';
-import type { HubProtocol } from '@enkaku/hub-protocol';
-import type { Logger } from '@kubun/logger';
-import type { CreateHubClient } from './relay-manager.js';
-export type HubClientRef = {
-    client: Client<HubProtocol>;
-    refID: string;
-};
-/**
- * Fired once per freshly-spawned hub client when its first signed response
- * arrives. The pool binds the hub URL into the call site; consumers (hub
- * manager `captureServerDID`) use the URL to look up the local hub row and
- * apply the conflict matrix. Errors are caught and logged — capture never
- * blocks message forwarding, even on `HubServerDIDConflictError`.
- */
-export type OnServerDIDObserved = (params: {
-    hubURL: string;
-    serverDID: string;
-}) => void | Promise<void>;
-/**
- * Resolves the locally-pinned `server_did` for a hub URL at spawn time. When
- * the hub row for this URL exists and has `server_did` set, the pool passes
- * it as `expectedServerDID` to the client factory so the wrapper enforces
- * the pin. Returning `null` falls back to TOFU.
- *
- * Resolution happens fresh on every spawn so `updateHub({ serverDID: null })`
- * re-arms TOFU automatically: the next disposed/evicted client triggers a
- * fresh resolve.
- */
-export type ResolvePinnedServerDID = (hubURL: string) => Promise<string | null>;
-export type HubConnectionPoolParams = {
-    createHubClient: CreateHubClient;
-    logger?: Logger;
-    onServerDIDObserved?: OnServerDIDObserved;
-    resolvePinnedDID?: ResolvePinnedServerDID;
-};
-export declare class HubConnectionPool {
-    #private;
-    constructor(params: HubConnectionPoolParams);
-    acquire(hubURL: string): Promise<HubClientRef>;
-    release(hubURL: string, refID: string): Promise<void>;
-    disposeAll(): Promise<void>;
-}

package/lib/hub/connection-pool.js

@@ -1 +0,0 @@
-export class HubConnectionPool{#e;#t;#i;#r;#s=new Map;#n=0;constructor(e){this.#e=e.createHubClient,this.#t=e.logger,this.#i=e.onServerDIDObserved,this.#r=e.resolvePinnedDID}async acquire(e){let t=this.#s.get(e);if(null!=t&&null!=t.disposing&&(await t.disposing,this.#s.get(e)===t&&this.#s.delete(e),t=void 0),null==t){let i,r=this.#i;if(null!=this.#r)try{let t=await this.#r(e);null!=t&&(i=t)}catch(t){this.#t?.warn("failed to resolve pinned server DID, falling back to TOFU",{hubURL:e,error:t})}let s=await this.#e(e,{onServerDID:null==r?void 0:async t=>{try{await r({hubURL:e,serverDID:t})}catch(i){this.#t?.warn("hub server DID capture failed",{hubURL:e,serverDID:t,error:i})}},expectedServerDID:i,onMismatch:null==i?void 0:e=>{this.#t?.warn("hub server DID mismatch — pinning enforcement triggered",{hubURL:e.hubURL,expectedServerDID:e.expectedServerDID,observedServerDID:e.observedServerDID})}}),n={client:s,refs:new Set};t=n,this.#s.set(e,n),s.disposed.then(()=>{this.#s.get(e)===n&&(this.#t?.debug("hub client disposed externally, evicting pool entry",{hubURL:e,outstandingRefs:[...n.refs]}),this.#s.delete(e))}).catch(()=>{})}let i=String(++this.#n);return t.refs.add(i),{client:t.client,refID:i}}async release(e,t){let i=this.#s.get(e);if(null==i)return void this.#t?.debug("HubConnectionPool.release: unknown hubURL",{hubURL:e,refID:t});if(!i.refs.has(t))return void this.#t?.debug("HubConnectionPool.release: unknown refID",{hubURL:e,refID:t});if(i.refs.delete(t),i.refs.size>0)return;let r=i.client.dispose();i.disposing=r;try{await r}finally{this.#s.get(e)===i&&this.#s.delete(e)}}async disposeAll(){let e=Array.from(this.#s.entries());await Promise.all(e.map(async([e,t])=>{t.refs.size>0&&this.#t?.warn("Disposing hub client with outstanding refs",{hubURL:e,refs:Array.from(t.refs)}),await t.client.dispose()})),this.#s.clear()}}

package/lib/hub/did-observing-transport.d.ts

@@ -1,64 +0,0 @@
-import { Disposer } from '@enkaku/async';
-import type { EventEmitter } from '@enkaku/event';
-import type { AnyClientMessageOf, AnyServerMessageOf, ClientTransportOf, ProtocolDefinition } from '@enkaku/protocol';
-import type { TransportEvents } from '@enkaku/transport';
-export type ServerDIDObserver = (serverDID: string) => void | Promise<void>;
-export type ServerDIDMismatchObserver = (params: {
-    hubURL: string;
-    expectedServerDID: string;
-    observedServerDID: string;
-}) => void;
-export type DIDObservingTransportParams<Protocol extends ProtocolDefinition> = {
-    inner: ClientTransportOf<Protocol>;
-    /**
-     * Fired on the first message bearing `payload.iss` when no `expectedServerDID`
-     * is set (TOFU capture). When `expectedServerDID` is set and matches, the
-     * callback is NOT fired — the pin is already authoritative.
-     */
-    onServerDID: ServerDIDObserver;
-    /**
-     * Pinned hub server DID. When set, the wrapper enforces it: a non-matching
-     * first observed `iss` triggers a permanent failed state — `read()` rejects
-     * with `HubServerDIDMismatchError`, the offending message is NOT delivered
-     * to the inner Client, and every subsequent `read()` re-raises the same
-     * error. When unset, the wrapper falls back to TOFU capture.
-     */
-    expectedServerDID?: string;
-    /** Hub URL — only used to populate `HubServerDIDMismatchError` for callers. */
-    hubURL?: string;
-    /**
-     * Optional side-channel notification fired on mismatch. Lets the pool log /
-     * evict without having to inspect the rejected `read()` cause. Inner
-     * transport disposal is the pool's job, not the wrapper's.
-     */
-    onMismatch?: ServerDIDMismatchObserver;
-};
-/**
- * Wraps a `ClientTransportOf<Protocol>` to enforce hub-server-DID
- * TOFU + pinned-mismatch semantics on the receive side.
- *
- * - `expectedServerDID == null`: TOFU mode. First message bearing
- *   `payload.iss` fires `onServerDID(iss)` exactly once; subsequent messages
- *   never re-fire, even with a differing `iss`. Every message is forwarded
- *   to the inner Client untouched.
- * - `expectedServerDID != null` and the first observed `iss` matches: the
- *   pin is already authoritative; `onServerDID` is NOT fired and forwarding
- *   continues normally.
- * - `expectedServerDID != null` and the first observed `iss` differs: the
- *   wrapper enters a permanent failed state (`HubServerDIDMismatchError`).
- *   The current `read()` call AND every subsequent `read()` reject with the
- *   error; the offending message is NOT delivered. Inner-transport lifecycle
- *   stays the pool's responsibility — the wrapper does not dispose its inner.
- *
- * Extends `Disposer` and matches the `ClientTransportOf<Protocol>` shape
- * structurally so it can be passed straight to `Client<Protocol>`.
- */
-export declare class DIDObservingTransport<Protocol extends ProtocolDefinition> extends Disposer {
-    #private;
-    constructor(params: DIDObservingTransportParams<Protocol>);
-    get events(): EventEmitter<TransportEvents>;
-    getWritable(): WritableStream<AnyClientMessageOf<Protocol>>;
-    read(): Promise<ReadableStreamReadResult<AnyServerMessageOf<Protocol>>>;
-    write(value: AnyClientMessageOf<Protocol>): Promise<void>;
-    [Symbol.asyncIterator](): AsyncIterator<AnyServerMessageOf<Protocol>, AnyServerMessageOf<Protocol> | null>;
-}

package/lib/hub/did-observing-transport.js

@@ -1 +0,0 @@
-import{Disposer as e}from"@enkaku/async";import{HubServerDIDMismatchError as r}from"./errors.js";export class DIDObservingTransport extends e{#e;#r;#t;#n;#i;#s=!1;#l=null;constructor(e){super({signal:e.inner.signal,dispose:async r=>{await e.inner.dispose(r)}}),this.#e=e.inner,this.#r=e.onServerDID,this.#t=e.expectedServerDID,this.#n=e.hubURL,this.#i=e.onMismatch}get events(){return this.#e.events}getWritable(){return this.#e.getWritable()}async read(){if(null!=this.#l)throw this.#l;let e=await this.#e.read(),r=this.#a(e);if(null!=r)throw r;return e}async write(e){await this.#e.write(e)}[Symbol.asyncIterator](){return{next:async()=>{let e=await this.read();return e.done?{done:!0,value:e.value??null}:{done:!1,value:e.value}}}}#a(e){if(this.#s||e.done||null==e.value)return null;let t=e.value.payload,n=t?.iss;if("string"!=typeof n||0===n.length)return null;if(this.#s=!0,null!=this.#t){if(n===this.#t)return null;let e=new r({hubURL:this.#n??"",expectedServerDID:this.#t,observedServerDID:n});if(this.#l=e,null!=this.#i)try{this.#i({hubURL:this.#n??"",expectedServerDID:this.#t,observedServerDID:n})}catch{}return e}return Promise.resolve().then(()=>this.#r(n)).catch(()=>{}),null}}

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

@@ -1,18 +0,0 @@
-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

@@ -1 +0,0 @@
-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,30 +0,0 @@
-export declare class ReconnectingError extends Error {
-    #private;
-    constructor(hubURL: string, attempt: number);
-    get hubURL(): string;
-    get attempt(): number;
-}
-/**
- * Thrown by `DIDObservingTransport.read()` when the first observed `payload.iss`
- * does not match the pinned `expectedServerDID`. The transport enters a
- * permanent failed state: no message bearing the offending `iss` is delivered
- * to the inner Client, and every subsequent `read()` rejects with the same
- * error. In-flight Enkaku RPCs see this error as the `cause` of the Client's
- * "Transport read failed" abort.
- *
- * Distinct from `HubServerDIDConflictError` (raised by manager-level
- * `captureServerDID` when the pin row already differs from the observed DID
- * on the TOFU capture path); this class is raised client-side, before any
- * message is delivered, when a row was already pinned at connect time.
- */
-export declare class HubServerDIDMismatchError extends Error {
-    #private;
-    constructor(params: {
-        hubURL: string;
-        expectedServerDID: string;
-        observedServerDID: string;
-    });
-    get hubURL(): string;
-    get expectedServerDID(): string;
-    get observedServerDID(): string;
-}

package/lib/hub/errors.js

@@ -1 +0,0 @@
-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/forward-remote-broadcast.d.ts

@@ -1,15 +0,0 @@
-import type { Logger } from '@kubun/logger';
-import type { BroadcastEvent } from '../groups/broadcast-service.js';
-import type { P2PEventEmitter } from '../groups/events.js';
-/**
- * Map a `BroadcastEvent` from `BroadcastService` into the matching
- * `P2PEventEmitter` event.
- *
- * - Events with `applied === false` are ignored (no state change).
- * - `catalog:*` messages are currently a no-op. Catalog send-side broadcasts
- *   and event propagation are deferred to a future task (see design spec).
- * - Payloads are built from `event.affected.row`, which `processBroadcast`
- *   captures at the appropriate moment (after-state for create / update,
- *   before-state for delete / remove).
- */
-export declare function forwardRemoteBroadcast(emitter: P2PEventEmitter, event: BroadcastEvent, logger?: Logger): Promise<void>;

package/lib/hub/forward-remote-broadcast.js

@@ -1 +0,0 @@
-import{toISO as e}from"../context/types.js";export async function forwardRemoteBroadcast(r,t,a){if(!t.applied)return;let{message:i,affected:c}=t;if("delegation:share"!==i.type){if(null==c)return void a?.warn("remote broadcast applied but affected row missing",{type:i.type});switch(i.type){case"circle:create":{if("circle"!==c.kind)return;let{row:t}=c;await r.emit("circleCreated",{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at)});return}case"circle:update":{if("circle"!==c.kind)return;let{row:t}=c,a=null!=i.update.catalogIDs?"circleCatalogsChanged":"circleDataChanged";await r.emit(a,{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at),circleID:t.id});return}case"circle:delete":{if("circle"!==c.kind)return;let{row:t}=c;await r.emit("circleDeleted",{id:t.id,groupID:t.group_id,name:t.name,description:t.description,createdAt:e(t.created_at)});return}case"member:add":{if("member"!==c.kind)return;let{row:t}=c;await r.emit("circleMemberAdded",{circleID:t.circle_id,memberDID:t.member_did,role:t.role,createdAt:e(t.created_at)});return}case"member:remove":{if("member"!==c.kind)return;let{row:t}=c;await r.emit("circleMemberRemoved",{circleID:t.circle_id,memberDID:t.member_did,role:t.role,createdAt:e(t.created_at)});return}case"group:update":{if("group"!==c.kind)return;let{row:t}=c;await r.emit("groupDataChanged",{id:t.id,name:t.name,description:t.description,createdBy:t.created_by,createdAt:e(t.created_at),groupID:t.id});return}case"catalog:create":case"catalog:update":case"catalog:delete":return void a?.debug("catalog broadcast ignored (not yet wired)",{type:i.type})}}}

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

@@ -1,89 +0,0 @@
-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;
-    send: (ids: Array<string>) => Promise<void>;
-    logger?: Logger;
-};
-export declare class AckBatch {
-    #private;
-    constructor(params: AckBatchParams);
-    add(id: string): void;
-    /**
-     * Drain the pending id set and send it via the configured sender. Never
-     * rejects: send errors are logged and the ids are dropped silently (the hub
-     * will redeliver unacknowledged messages, so the next receive will produce a
-     * fresh ack).
-     */
-    flush(): Promise<void>;
-    dispose(): void;
-}
-export declare function computeBackoff(attempt: number, base: number, max: number, jitter: number): number;
-export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;
-export type GroupChannelParams = {
-    groupID: string;
-    deviceID: string;
-    hubConnection: HubConnection;
-    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`.
- *
- * `open()` subscribes to the connection (issuing `hub/group/join` once),
- * `close()` unsubscribes (drains the per-group mutex then issues
- * `hub/group/leave`), and `broadcast()` runs the MLS encrypt+send pipeline
- * inside `HubConnection.runInGroup()` so the per-group mutex serializes send
- * and receive on the same MLS state.
- *
- * All transport state (refID, ack batching, receive loop, reconnect/backoff)
- * lives on `HubConnection` and is shared across every channel for that
- * `hubURL`. A peer with N groups uses ONE `hub/receive` stream per
- * `(deviceDID, hubURL)` rather than N — this preserves the hub-server's
- * single-writer-per-DID invariant for bridge peers.
- */
-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;
-    }): Promise<void>;
-    /**
-     * Fan out a pre-produced MLS handshake Commit to the group's existing
-     * members. Mirrors {@link broadcast} but routes through `handleSendCommit`
-     * (no application encryption — the Commit is already self-protected).
-     */
-    sendCommit(commitBytes: Uint8Array, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-}

package/lib/hub/group-channel.js

@@ -1 +0,0 @@
-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/hub-connection.d.ts

@@ -1,96 +0,0 @@
-import { Disposer } from '@enkaku/async';
-import { EventEmitter } from '@enkaku/event';
-import type { StoredMessage } from '@enkaku/hub-protocol';
-import type { Logger } from '@kubun/logger';
-import type { HubConnectionPool } from './connection-pool.js';
-import type { ReceivedHubMessage } from './receive-handler.js';
-export type TunnelMessageStream = AsyncIterable<StoredMessage> & {
-    return(): void;
-};
-export type TunnelMessageStreamParams = {
-    peerDID: string;
-};
-export type SubscriptionHandler = (message: ReceivedHubMessage) => Promise<{
-    ack: boolean;
-}>;
-export type ConnectionLifecycleEvent = {
-    type: 'connected';
-} | {
-    type: 'disconnected';
-    reason?: string;
-} | {
-    type: 'error';
-    error: unknown;
-} | {
-    type: 'reconnecting';
-    attempt: number;
-    delayMs: number;
-};
-type HubConnectionEvents = {
-    lifecycle: ConnectionLifecycleEvent;
-};
-export type HubConnectionParams = {
-    hubURL: string;
-    deviceID: string;
-    pool: HubConnectionPool;
-    logger?: Logger;
-    ackFlushMs?: number;
-    ackFlushMax?: number;
-    backoffBaseMs?: number;
-    backoffMaxMs?: number;
-    backoffJitter?: number;
-};
-export declare class HubConnection extends Disposer {
-    #private;
-    constructor(params: HubConnectionParams);
-    get events(): EventEmitter<HubConnectionEvents>;
-    open(): Promise<void>;
-    subscribe(groupID: string, credential: string, handler: SubscriptionHandler): Promise<void>;
-    unsubscribe(groupID: string): Promise<void>;
-    broadcast(groupID: string, encryptedPayload: string, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-    /**
-     * Send an opaque tunnel-style message to explicit recipients via
-     * `hub/send`. No `groupID` is attached at the hub level — recipients
-     * receive the message on the tunnel-routing path (see
-     * {@link tunnelMessageStream}). Used by hub-mediated document sync.
-     */
-    send(params: {
-        recipients: Array<string>;
-        payload: Uint8Array;
-        timeoutMs?: number;
-    }): Promise<{
-        sequenceID: string;
-    }>;
-    /**
-     * Run `fn` inside the same per-group mutex used by receive `#dispatch`. This
-     * lets callers (e.g. `GroupChannel.broadcast`) serialize MLS-state-mutating
-     * pipelines with incoming-message handling on the same group, avoiding races
-     * between concurrent send-encrypt and receive-decrypt against shared MLS
-     * group state.
-     *
-     * The gate-await ensures the subscription map is settled before lookup —
-     * i.e. mid-reconnect callers wait for the subscription to be (re)registered
-     * rather than throwing.
-     */
-    runInGroup<T>(groupID: string, fn: () => Promise<T>, opts?: {
-        timeoutMs?: number;
-    }): Promise<T>;
-    /**
-     * Register a per-peer tunnel inbox and return a disposable async iterable
-     * of {@link StoredMessage} values received from that peer over the tunnel
-     * (i.e. direct hub messages with no `groupID`).
-     *
-     * Used by the hub-mediated document sync server adapter (see Q3 of the
-     * hub-mediated document sync plan). The hub's receive-side dispatcher
-     * keys tunnel routing on `senderDID` because hub-level messages cannot
-     * reveal the in-frame `sessionID` (the body is encrypted). P2P pairs
-     * `peerDID` and `sessionID` at session creation, so peer-keying is
-     * sufficient. Concurrent tunnel sessions to the same peer are not
-     * supported and are the caller's responsibility to avoid.
-     */
-    tunnelMessageStream({ peerDID }: TunnelMessageStreamParams): TunnelMessageStream;
-    close(): Promise<void>;
-}
-export {};

package/lib/hub/hub-connection.js

@@ -1 +0,0 @@
-import{Disposer as e}from"@enkaku/async";import{fromB64 as t,toB64 as s}from"@enkaku/codec";import{EventEmitter as n}from"@enkaku/event";import{createMutex as i}from"../util/mutex.js";import{ReconnectingError as r}from"./errors.js";import{AckBatch as o,abortableSleep as h,computeBackoff as a}from"./group-channel.js";import{TunnelInbox as c}from"./tunnel-inbox.js";import{waitForGate as l}from"./wait-for-gate.js";let u=Symbol("disposed");export class HubConnection extends e{#e;#t;#s;#n;#i;#r;#o;#h;#a;#c=null;#l=null;#u=null;#b=null;#p=null;#d=new Map;#f=!1;#g=0;#m=null;#y=new Map;#w;constructor(e){super({dispose:async()=>{await this.#L()}}),this.#e=e.hubURL,this.#t=e.deviceID,this.#s=e.pool,this.#n=e.logger,this.#i=e.ackFlushMs??500,this.#r=e.ackFlushMax??10,this.#o=e.backoffBaseMs??1e3,this.#h=e.backoffMaxMs??6e4,this.#a=e.backoffJitter??.25,this.#w=new n}get events(){return this.#w}async #I(e){try{await this.#w.emit("lifecycle",e)}catch(t){this.#n?.warn("hub-connection lifecycle subscriber threw",{hubURL:this.#e,type:e.type,error:t})}}async open(){if(this.#f)throw Error("HubConnection already opened");try{await this.#k(),this.#f=!0,await this.#I({type:"connected"})}catch(e){if(null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release after open failure failed",{hubURL:this.#e,error:e})}this.#l=null}throw this.#c=null,e}}async #k(){if(null!=this.#l){let e=this.#l;this.#l=null,this.#c=null;try{await this.#s.release(this.#e,e)}catch(e){this.#n?.debug("hub-connection pool release before reconnect failed",{hubURL:this.#e,error:e})}}let{client:e,refID:t}=await this.#s.acquire(this.#e);this.#c=e,this.#l=t;let s=e.createChannel("hub/receive",{param:{},signal:this.signal});this.#u=s,s.catch(()=>{}),this.#b=new o({flushMs:this.#i,flushMax:this.#r,send:async e=>{await s.send({ack:e})},logger:this.#n}),this.#p=this.#R(e).catch(e=>{this.#n?.debug("hub-connection receive task tail error",{hubURL:this.#e,error:e})});let n=[...this.#d.entries()];if(n.length>0){let t=await Promise.allSettled(n.map(async([t,s])=>{await e.request("hub/group/join",{param:{groupID:t,credential:s.credential}})}));for(let e=0;e<t.length;e++){let s=t[e];if("rejected"===s.status){let t=n[e][0];this.#n?.warn("hub-connection rejoin failed",{hubURL:this.#e,groupID:t,error:s.reason})}}}}async subscribe(e,t,s){if(await l(this.#m,void 0),!this.#f||null==this.#c)throw Error("HubConnection not open");if(this.#d.has(e))throw Error(`already subscribed to group ${e}`);await this.#c.request("hub/group/join",{param:{groupID:e,credential:t}}),this.#d.set(e,{credential:t,handler:s,mutex:i()})}async unsubscribe(e){await l(this.#m,void 0);let t=this.#c;if(!this.#f||null==t)throw Error("HubConnection not open");let s=this.#d.get(e);if(null==s)throw Error(`not subscribed to group ${e}`);await s.mutex.run(async()=>{}),await t.request("hub/group/leave",{param:{groupID:e}}),this.#d.delete(e)}async broadcast(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");await this.#c.request("hub/group/send",{param:{groupID:e,payload:t}})}async send(e){if(await l(this.#m,e.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f||null==this.#c)throw Error("HubConnection not open");return{sequenceID:(await this.#c.request("hub/send",{param:{recipients:e.recipients,payload:s(e.payload)}})).sequenceID}}async runInGroup(e,t,s){if(await l(this.#m,s?.timeoutMs,()=>new r(this.#e,this.#g)),!this.#f)throw Error("HubConnection not open");let n=this.#d.get(e);if(null==n)throw Error(`not subscribed to group ${e}`);return n.mutex.run(t)}tunnelMessageStream({peerDID:e}){if(this.#y.has(e))throw Error("tunnelMessageStream: peerDID already registered");let t=new c,s={inbox:t};this.#y.set(e,s);let n=!1;return{[Symbol.asyncIterator]:()=>t.iterator(),return:()=>{n||(n=!0,this.#y.get(e)===s&&this.#y.delete(e),t.close())}}}async #R(e){let t=this.#u;if(null==t)return;let s=t.readable.getReader(),n=null;try{for(;!this.signal.aborted;){let t=s.read(),n=e.disposed.then(()=>u),i=await Promise.race([t,n]);if("symbol"==typeof i){this.#n?.debug("hub-connection receive loop observed hub client disposal",{hubURL:this.#e});break}let{done:r,value:o}=i;if(r)break;this.#D(o),this.#g=0}}catch(e){n=e,this.#n?.warn("hub-connection receive loop error",{hubURL:this.#e,error:e})}finally{try{s.releaseLock()}catch{}}if(!this.signal.aborted){let e=n instanceof Error&&n.message?n.message:"receive loop ended";await this.#I({type:"disconnected",reason:e}),this.#U()}}#U(){this.#p=this.#M().catch(e=>{this.#n?.debug("hub-connection reconnect task tail error",{hubURL:this.#e,error:e})})}async #M(){let e=()=>{};this.#m=new Promise(t=>{e=t});try{for(;!this.signal.aborted;){let e=a(this.#g++,this.#o,this.#h,this.#a);this.#n?.debug("hub-connection reconnect scheduled",{hubURL:this.#e,delay:e,attempt:this.#g});try{await h(e,this.signal)}catch{return}await this.#I({type:"reconnecting",attempt:this.#g,delayMs:e});try{this.#b?.dispose(),this.#b=null,this.#u=null,await this.#k(),this.#g=0,await this.#I({type:"connected"});return}catch(e){this.#n?.warn("hub-connection reconnect attempt failed",{hubURL:this.#e,attempt:this.#g,error:e}),await this.#I({type:"error",error:e})}}}finally{this.#m=null,e()}}#D(e){if(null==e.groupID){let s=this.#y.get(e.senderDID);if(null!=s){let n={sequenceID:e.sequenceID,senderDID:e.senderDID,payload:t(e.payload)};s.inbox.push(n),this.#b?.add(e.sequenceID);return}this.#n?.debug("direct message received, no handler",{hubURL:this.#e,sequenceID:e.sequenceID}),this.#b?.add(e.sequenceID);return}let s=this.#d.get(e.groupID);null==s?this.#n?.debug("message for unsubscribed group",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID}):s.mutex.run(()=>s.handler(e)).then(t=>{t.ack&&this.#b?.add(e.sequenceID)}).catch(t=>{this.#n?.warn("hub-connection subscription handler error",{hubURL:this.#e,groupID:e.groupID,sequenceID:e.sequenceID,error:t})})}async close(){this.#f&&await this.dispose()}async #L(){if(!this.#f)return;let e=this.#b;if(this.#b=null,null!=e){try{await e.flush()}catch(e){this.#n?.debug("hub-connection ack flush during close failed",{hubURL:this.#e,error:e})}e.dispose()}try{this.#u?.close()}catch{}try{await this.#p}catch{}let t=[...this.#d.values()].map(e=>e.mutex.run(async()=>{}).catch(()=>{}));if(await Promise.allSettled(t),null!=this.#l){try{await this.#s.release(this.#e,this.#l)}catch(e){this.#n?.debug("hub-connection pool release during close failed",{hubURL:this.#e,error:e})}this.#l=null}for(let e of(this.#c=null,this.#u=null,this.#p=null,this.#d.clear(),this.#y.values()))e.inbox.close();this.#y.clear(),this.#f=!1}}

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

@@ -1,51 +0,0 @@
-import type { Logger } from '@kubun/logger';
-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.
- */
-export type ReceivedHubMessage = {
-    sequenceID: string;
-    senderDID: string;
-    groupID?: string;
-    /** base64-encoded encrypted MLS application message */
-    payload: string;
-};
-export type HandleReceivedMessageParams = {
-    groupID: string;
-    message: ReceivedHubMessage;
-    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.
- *
- * Returns `{ ack: true }` when the message has been processed to a state where
- * redelivery serves no purpose (applied successfully, or decrypt failed with
- * 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. The `outcome` classifies the result for health tracking.
- */
-export declare function handleReceivedMessage(params: HandleReceivedMessageParams): Promise<HandleReceivedMessageResult>;

package/lib/hub/receive-handler.js

@@ -1 +0,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}}