@kubun/plugin-p2p 0.10.0 → 0.11.0

package/lib/groups/group-handle-registry.js

@@ -1 +1,243 @@
-import{getKubunLogger as e}from"@kubun/logger";import{getP2PStore as t}from"@kubun/store-p2p";import{createMutex as r}from"../util/mutex.js";import{restoreMLSGroupHandle as s}from"./mls-group-handle.js";import{fromMLSStateRow as i,serializeMLSGroupState as a,toMLSStateInsert as l}from"./mls-state.js";export class GroupHandleRegistry{#e;#t;#r;#s=new Map;constructor(t){this.#e=t.stores,this.#t=t.deviceID,this.#r=t.logger??e("plugin-p2p:group-handle-registry")}withHandle(e,t,r){return this.#i(e,r,async(r,s)=>{let i=await t(r.handle);return await this.#a(s,e,r.handle),i})}withHandleReplacing(e,t,r){return this.#i(e,r,async(r,s)=>{let{result:i,updated:a}=await t(r.handle);return r.handle=a,await this.#a(s,e,a),i})}#i(e,t,r){let s=t?.stores??this.#e,i=this.#l(e);return i.mutex.run(async()=>(null==i.handle&&(i.handle=await this.#n(s,e)),r(i,s)))}invalidate(e){this.#s.delete(e)}async seed(e){let{groupID:r,handle:s,stores:i}=e,n=this.#s.get(r);if(n?.handle!=null)throw Error(`GroupHandleRegistry.seed: handle already cached for group ${r}`);let o=a(s),h=await t(i);await h.saveMLSState(l(o,r,this.#t)),i.onCommit(()=>{let e=this.#l(r);null==e.handle&&(e.handle=s)})}#l(e){let t=this.#s.get(e);return null==t&&(t={handle:null,mutex:r()},this.#s.set(e,t)),t}async #n(e,r){let a=await t(e),l=await a.getMLSState(r,this.#t);if(null==l)throw this.#r.debug("restore: no MLS state",{groupID:r,deviceID:this.#t}),Error(`No MLS state for group ${r}`);return this.#r.debug("restore: MLS state",{groupID:r,deviceID:this.#t,epoch:l.epoch}),await s(i(l))}async #a(e,r,s){let i=a(s),n=await t(e);await n.saveMLSState(l(i,r,this.#t)),this.#r.debug("persist: MLS state",{groupID:r,deviceID:this.#t,epoch:i.epoch})}}
+import { getKubunLogger } from '@kubun/logger';
+import { getP2PStore } from '@kubun/store-p2p';
+import { createMutex } from '../util/mutex.js';
+import { restoreMLSGroupHandle } from './mls-group-handle.js';
+import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls-state.js';
+/**
+ * Single canonical access point for a device's MLS `GroupHandle` instances.
+ *
+ * Owns the per-group async mutex covering encrypt/decrypt and epoch-bumping
+ * operations, and persists the (possibly mutated) handle on every successful
+ * `withHandle` callback. On callback throw, persist is skipped; the in-memory
+ * handle retains its mutated state so the caller can decide whether to retry.
+ *
+ * All five mutation paths (manager member ops, context handlers, broadcast
+ * service encrypt/decrypt, hub-tunnel sync listener, hub-tunnel sync provider)
+ * route MLS state through this registry. Spec:
+ * `docs/superpowers/specs/2026-05-09-group-handle-registry-design.md`.
+ */ export class GroupHandleRegistry {
+    #stores;
+    #deviceID;
+    #logger;
+    #entries = new Map();
+    constructor(params){
+        this.#stores = params.stores;
+        this.#deviceID = params.deviceID;
+        this.#logger = params.logger ?? getKubunLogger('plugin-p2p:group-handle-registry');
+    }
+    /**
+   * Acquire the canonical handle for `groupID`, run `fn` under the per-group
+   * mutex, persist the (possibly mutated) handle on success, release.
+   * On throw, persist is skipped; in-memory handle retains its mutated state.
+   *
+   * Use this for in-place mutating ops (encrypt/decrypt) and reads. For
+   * epoch-bumping ops that produce a fresh `GroupHandle` (commitInvite,
+   * removeMember, processCommit), use `withHandleReplacing` instead.
+   *
+   * Bound: when called under a caller transaction that commits later, this
+   * mutates/eager-uses the shared cached handle and releases the mutex before
+   * that commit, so a concurrent same-group op can observe the uncommitted
+   * handle during the window. `onRollback` repairs the cache after a rollback;
+   * the live exposure is a concurrent cross-epoch decrypt during a rolling-back
+   * membership mutation, which fails the MLS check and skips its persist (a
+   * dropped message, never a durable divergence), and only on a multi-connection
+   * adapter. The transactional epoch-bumping path uses
+   * `withHandleReplacingInTransaction` (fresh handle + mutex held across commit)
+   * to avoid the window entirely.
+   *
+   * `options.stores` overrides the constructor-stored `StoreProvider` for the
+   * restore + persist DB calls. Callers running inside an engine transaction
+   * (e.g. context handlers under `mutateGraph`) MUST pass the transactional
+   * `tx` so reads + writes share the tx's connection. Without this, SQLite's
+   * write lock held by the outer tx blocks the registry's persist forever.
+   */ withHandle(groupID, fn, options) {
+        return this.#withLockedHandle(groupID, options, async (entry, stores)=>{
+            const result = await fn(entry.handle);
+            await this.#persist(stores, groupID, entry.handle);
+            // `fn` may have mutated the handle in place before the persist; if the
+            // surrounding transaction rolls back, the DB row reverts but the cached
+            // handle stays advanced, so drop it and re-restore on next access.
+            stores.onRollback(()=>this.invalidate(groupID));
+            return result;
+        });
+    }
+    /**
+   * Acquire the canonical handle for `groupID`, run `fn` under the per-group
+   * mutex, return the result, release — WITHOUT persisting MLS state.
+   *
+   * Read-only access: takes the lock and lazy-restores the cached handle if
+   * absent, but never writes MLS state. Use this for pure reads that do not
+   * mutate the handle (anchor reads, `GroupInfo` export, credential reads). For
+   * in-place-mutating ops that advance the MLS secret tree (encrypt/decrypt),
+   * use `withHandle`, which persists the advanced state.
+   */ readHandle(groupID, fn, options) {
+        return this.#withLockedHandle(groupID, options, async (entry)=>{
+            return await fn(entry.handle);
+        });
+    }
+    /**
+   * Like `withHandle`, but the callback returns `{ result, updated }`.
+   * Registry replaces its cached handle with `updated` before persisting on
+   * success. Required for `@kumiai/mls` epoch ops (`commitInvite`,
+   * `removeMember`, `processCommit`) which construct a fresh `GroupHandle`
+   * rather than mutating the input.
+   *
+   * `options.stores` follows the same semantics as `withHandle.options.stores`.
+   */ withHandleReplacing(groupID, fn, options) {
+        return this.#withLockedHandle(groupID, options, async (entry, stores)=>{
+            const { result, updated } = await fn(entry.handle);
+            entry.handle = updated;
+            await this.#persist(stores, groupID, updated);
+            // Eager swap: the cache now holds the advanced handle but the persist is
+            // uncommitted. If the surrounding transaction rolls back, the DB row
+            // reverts while the cache stays advanced, so drop it and re-restore the
+            // reverted row on next access.
+            stores.onRollback(()=>this.invalidate(groupID));
+            return result;
+        });
+    }
+    /**
+   * Like `withHandleReplacing`, but the per-group mutex is held across the
+   * ENTIRE transaction — it is acquired once, then a transaction is opened, run,
+   * and committed under that single lock, which releases only AFTER commit (or
+   * rollback). The cached `entry.handle` is NEVER touched by this method; the
+   * cache swap is the `onCommit` invalidation.
+   *
+   * Use this when the MLS advance must commit or roll back together with other
+   * rows written in the same transaction (e.g. receive-side commit processing
+   * that advances the ratchet AND writes the roster delta). `fn` receives both
+   * the working handle and the transactional `StoreProvider` so it can write
+   * those other rows on the same connection.
+   *
+   * WHY the lock spans commit: holding the mutex until after commit means the
+   * `onCommit` invalidation fires while the lock is still held. By the time a
+   * concurrent same-group op acquires the lock, the cache is already invalidated
+   * and the committed advanced row is durable, so the concurrent op re-restores
+   * the advanced handle. There is no post-mutex / pre-commit window for a
+   * concurrent op to interleave and clobber the advance.
+   *
+   * WHY a fresh working handle rather than the cached one: epoch ops here
+   * advance the MLS ratchet IN PLACE (`handle.processMessage` mutates the handle
+   * object and returns bytes, not a fresh handle). If the callback ran against
+   * the cached `entry.handle`, that in-place mutation would advance the cache
+   * immediately — but the transaction is still uncommitted. On ROLLBACK the DB
+   * ratchet row reverts while the cached handle stays advanced, so cache and DB
+   * diverge. Restoring a throwaway working handle keeps the cache untouched: on
+   * rollback the cache still matches the reverted DB; on commit the cache is
+   * invalidated and the next access lazily re-restores the committed advanced
+   * state. This costs one extra MLS-state restore per call.
+   */ async withHandleReplacingInTransaction(groupID, stores, fn) {
+        const entry = this.#getOrCreateEntry(groupID);
+        return entry.mutex.run(async ()=>{
+            return await stores.withTransaction(async (tx)=>{
+                const workingHandle = await this.#restore(tx, groupID);
+                const { result, updated } = await fn(workingHandle, tx);
+                await this.#persist(tx, groupID, updated);
+                tx.onCommit(()=>this.invalidate(groupID));
+                return result;
+            });
+        });
+    }
+    /**
+   * Shared prelude: resolve stores, get-or-create entry, acquire per-group
+   * mutex, lazy-restore on first acquire, run `fn` (which is responsible for
+   * the post-callback persist + cache update). Centralizes lock/restore
+   * semantics so `withHandle` and `withHandleReplacing` cannot drift.
+   */ #withLockedHandle(groupID, options, fn) {
+        const stores = options?.stores ?? this.#stores;
+        const entry = this.#getOrCreateEntry(groupID);
+        return entry.mutex.run(async ()=>{
+            if (entry.handle == null) {
+                entry.handle = await this.#restore(stores, groupID);
+            }
+            return fn(entry, stores);
+        });
+    }
+    /**
+   * Drop the cached handle for `groupID`. Next `withHandle` re-restores from DB.
+   * Called by `leaveGroup` after the MLS state row is deleted, and by tests.
+   */ invalidate(groupID) {
+        this.#entries.delete(groupID);
+    }
+    /**
+   * Atomically swap+persist the cached handle under the per-group mutex, so a
+   * concurrent decrypt runs strictly before (stale handle, fails harmlessly) or
+   * after (new handle), never interleaved.
+   */ replaceHandle(groupID, handle, options) {
+        return this.#withLockedHandle(groupID, options, async (entry, stores)=>{
+            entry.handle = handle;
+            await this.#persist(stores, groupID, handle);
+            // Eager swap: if the surrounding transaction rolls back, the DB row
+            // reverts while the cache holds the swapped handle, so drop it and
+            // re-restore the reverted row on next access.
+            stores.onRollback(()=>this.invalidate(groupID));
+        });
+    }
+    /**
+   * Prime the cache with a freshly-built handle and persist the initial row
+   * via the supplied transactional `StoreProvider`. Called by `createGroup`
+   * and `joinGroup` so the row write rolls back with the rest of the
+   * create/join transaction on `withTransaction` abort. The cache install is
+   * deferred to `stores.onCommit` so a rollback leaves the cache empty.
+   *
+   * Must NOT be called concurrently with `withHandle` / `withHandleReplacing`
+   * on the same `groupID`: the `seed` row write is uncommitted until the
+   * surrounding transaction completes, so a concurrent `withHandle` whose
+   * mutex region runs before commit would `#restore` from a missing row.
+   * `createGroup` and `joinGroup` only seed for fresh groups not yet visible
+   * to other callers, so this constraint is naturally satisfied in practice.
+   */ async seed(params) {
+        const { groupID, handle, stores } = params;
+        const existing = this.#entries.get(groupID);
+        if (existing?.handle != null) {
+            throw new Error(`GroupHandleRegistry.seed: handle already cached for group ${groupID}`);
+        }
+        const serialized = serializeMLSGroupState(handle);
+        const p2pStore = await getP2PStore(stores);
+        await p2pStore.saveMLSState(toMLSStateInsert(serialized, groupID, this.#deviceID));
+        stores.onCommit(()=>{
+            const entry = this.#getOrCreateEntry(groupID);
+            if (entry.handle == null) {
+                entry.handle = handle;
+            }
+        });
+    }
+    #getOrCreateEntry(groupID) {
+        let entry = this.#entries.get(groupID);
+        if (entry == null) {
+            entry = {
+                handle: null,
+                mutex: createMutex()
+            };
+            this.#entries.set(groupID, entry);
+        }
+        return entry;
+    }
+    async #restore(stores, groupID) {
+        const p2pStore = await getP2PStore(stores);
+        const row = await p2pStore.getMLSState(groupID, this.#deviceID);
+        if (row == null) {
+            this.#logger.debug('restore: no MLS state', {
+                groupID,
+                deviceID: this.#deviceID
+            });
+            throw new Error(`No MLS state for group ${groupID}`);
+        }
+        this.#logger.debug('restore: MLS state', {
+            groupID,
+            deviceID: this.#deviceID,
+            epoch: row.epoch
+        });
+        return await restoreMLSGroupHandle(fromMLSStateRow(row));
+    }
+    async #persist(stores, groupID, handle) {
+        const serialized = serializeMLSGroupState(handle);
+        const p2pStore = await getP2PStore(stores);
+        await p2pStore.saveMLSState(toMLSStateInsert(serialized, groupID, this.#deviceID));
+        this.#logger.debug('persist: MLS state', {
+            groupID,
+            deviceID: this.#deviceID,
+            epoch: serialized.epoch
+        });
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { ProcessBroadcastParams } from './broadcast.js';
+import type { ControlProtocol, SyncProtocol } from './group-protocols.js';
+/**
+ * The two app-lane handler maps a per-group peer wires into `createGroupPeer`.
+ * Keyed to {@link groupProtocols} so the peer dispatches each decoded procedure
+ * payload to the matching handler.
+ */
+export type GroupHandlers = {
+    control: ProcedureHandlers<ControlProtocol>;
+    sync: ProcedureHandlers<SyncProtocol>;
+};
+/**
+ * Build the control + sync procedure handlers for a single group.
+ *
+ * Each handler is a thin adapter: it maps the typed group-rpc procedure payload
+ * back to the {@link GroupBroadcastMessage} the pure {@link processBroadcast}
+ * apply logic already understands, re-adding the `groupID` the peer is bound to
+ * (group-rpc strips it from the wire because each topic already encodes the
+ * group). The apply logic owns verification, conflict resolution, and storage;
+ * the handler owns only the shape translation.
+ *
+ * Event handlers are fire-and-forget. `processBroadcast` already drops an
+ * unverifiable or malformed payload and returns `{ applied: false }` rather than
+ * throwing, so the result is intentionally ignored. A programmer-error rethrow
+ * (or an unexpected store fault) is caught and logged here so a single bad frame
+ * never escapes as an unhandled rejection out of the receive loop.
+ */
+export declare function buildGroupHandlers(params: ProcessBroadcastParams, groupID: string): GroupHandlers;

package/lib/groups/group-handlers.js

@@ -0,0 +1,92 @@
+import { isSignedToken } from '@kokuin/token';
+import { processBroadcast } from './broadcast.js';
+import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
+/**
+ * Build the control + sync procedure handlers for a single group.
+ *
+ * Each handler is a thin adapter: it maps the typed group-rpc procedure payload
+ * back to the {@link GroupBroadcastMessage} the pure {@link processBroadcast}
+ * apply logic already understands, re-adding the `groupID` the peer is bound to
+ * (group-rpc strips it from the wire because each topic already encodes the
+ * group). The apply logic owns verification, conflict resolution, and storage;
+ * the handler owns only the shape translation.
+ *
+ * Event handlers are fire-and-forget. `processBroadcast` already drops an
+ * unverifiable or malformed payload and returns `{ applied: false }` rather than
+ * throwing, so the result is intentionally ignored. A programmer-error rethrow
+ * (or an unexpected store fault) is caught and logged here so a single bad frame
+ * never escapes as an unhandled rejection out of the receive loop.
+ */ export function buildGroupHandlers(params, groupID) {
+    const safeApply = async (apply)=>{
+        try {
+            await apply();
+        } catch (error) {
+            params.logger?.warn('group handler apply failed', {
+                groupID,
+                error
+            });
+        }
+    };
+    return {
+        control: {
+            // Event handlers return the (never-rejecting) apply promise. The procedure
+            // contract types them `=> void`, so the server ignores the return; returning
+            // the promise is purely so a caller (e.g. a test) that holds the handler
+            // directly can await the apply completing.
+            'control/ledgerEntry': ({ data })=>safeApply(async ()=>{
+                    // A remote-applied ledger entry returns its circle/group projection row
+                    // as `affected` rather than emitting; surface the matching local events
+                    // so this receiver's GraphQL subscribers see the change live.
+                    const result = await processBroadcast(params, {
+                        type: 'ledger:entry',
+                        groupID,
+                        token: data.token
+                    }, groupID);
+                    if (params.emitter != null) {
+                        await emitLedgerAffectedEvents(params.emitter, result);
+                    }
+                }),
+            'control/delegationShare': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'delegation:share',
+                        token: data.token,
+                        groupID,
+                        hlc: data.hlc
+                    }, groupID)),
+            'control/delegationRevoke': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'delegation:revoke',
+                        token: data.token,
+                        groupID,
+                        hlc: data.hlc
+                    }, groupID)),
+            'control/groupLeaveRequest': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'group:leaveRequest',
+                        groupID,
+                        memberDID: data.memberDID,
+                        hlc: data.hlc
+                    }, groupID)),
+            'control/ledgerCatchup': async ()=>{
+                // Untrusted responder: hand back every stored signed entry token. The
+                // requester re-verifies each one independently, so authority lives in the
+                // token, not in this reply.
+                const rows = await params.p2pStore.getLedgerEntries(groupID);
+                return {
+                    entries: rows.map((row)=>row.signed_token)
+                };
+            }
+        },
+        sync: {
+            'sync/mutationApply': ({ data, message })=>{
+                // The authenticated transport sender is the signed frame's issuer. It is
+                // only a belt-and-suspenders loopback guard — the hub already fans a
+                // publish to subscribers minus the sender, so a peer never receives its
+                // own broadcast. An unsigned frame yields '' (harmless: no self-match).
+                const senderPeerDID = isSignedToken(message) ? message.payload.iss : '';
+                return safeApply(()=>processBroadcast(params, {
+                        type: 'mutation:apply',
+                        entries: data.entries,
+                        senderPeerDID
+                    }, groupID));
+            }
+        }
+    };
+}

package/lib/groups/group-health-monitor.d.ts

@@ -0,0 +1,56 @@
+import { type Logger } from '@kubun/logger';
+import type { GroupHealthCondition, GroupHealthSnapshot, GroupHealthState } from '../types.js';
+import type { P2PEventEmitter } from './events.js';
+export type GroupHealthMonitorParams = {
+    emitter: P2PEventEmitter;
+    /** Tuning for the `epoch-stale` condition. Defaults to a threshold of 3. */
+    epochStale?: {
+        threshold?: number;
+    };
+    /** Clock for `lastTransitionAt` stamps. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Logger for a throwing `groupHealthChanged` subscriber. Defaults to the
+     *  `group-health-monitor` namespace. */
+    logger?: Logger;
+};
+/**
+ * INERT: the mutating producers (`signal`/`reset`/`mark*`) have no live caller,
+ * so `getHealth` always reports `healthy` and `groupHealthChanged` never fires.
+ * This is the front-end of the epoch-stale-recovery feature, deliberately
+ * dormant until tier-2 Welcome re-admission exists — see
+ * docs/agents/plans/backlog/welcome-based-deep-recovery.md. Kept (not deleted)
+ * because that feature is roadmapped and this scaffolding is design-aligned.
+ *
+ * Per-group health state machine. Counts/latches failure signals per
+ * `(groupID, condition)` and emits `groupHealthChanged` on transitions.
+ * Crypto- and persistence-free: callers classify failures before signalling.
+ *
+ * State is in-memory per-process — a restart re-derives it from the next signal.
+ * Transitions are synchronous (no `await`), so calls cannot interleave; signals
+ * arriving while a rejoin is in flight (`recovering`) are ignored — the recovery
+ * owns the group until it resolves.
+ */
+export declare class GroupHealthMonitor {
+    #private;
+    constructor(params: GroupHealthMonitorParams);
+    /**
+     * Record a failure observation for a condition. Below the condition's
+     * threshold this only increments the counter; on reaching it the group
+     * transitions to `degraded` (emitted once, then latched). Ignored while the
+     * group is `recovering` (the rejoin owns it) or already `degraded`/failed.
+     */
+    signal(groupID: string, condition: GroupHealthCondition): void;
+    /**
+     * Clear a condition to healthy and re-arm (counter reset), driven by the
+     * success path. Silent: only recovery (via the mark* methods) is surfaced.
+     */
+    reset(groupID: string, condition: GroupHealthCondition): void;
+    markRecovering(groupID: string): void;
+    /** Emit the transient `recovered` event, then settle the phase to `healthy`. */
+    markRecovered(groupID: string): void;
+    /** Leave the group `recovery-failed` until a later success resets it. */
+    markRecoveryFailed(groupID: string): void;
+    /** Aggregate state: the first non-healthy condition phase, else `healthy`. */
+    getState(groupID: string): GroupHealthState;
+    getHealth(groupID: string): GroupHealthSnapshot;
+}

package/lib/groups/group-health-monitor.js

@@ -0,0 +1,139 @@
+import { getKubunLogger } from '@kubun/logger';
+const DEFAULT_EPOCH_STALE_THRESHOLD = 3;
+/**
+ * INERT: the mutating producers (`signal`/`reset`/`mark*`) have no live caller,
+ * so `getHealth` always reports `healthy` and `groupHealthChanged` never fires.
+ * This is the front-end of the epoch-stale-recovery feature, deliberately
+ * dormant until tier-2 Welcome re-admission exists — see
+ * docs/agents/plans/backlog/welcome-based-deep-recovery.md. Kept (not deleted)
+ * because that feature is roadmapped and this scaffolding is design-aligned.
+ *
+ * Per-group health state machine. Counts/latches failure signals per
+ * `(groupID, condition)` and emits `groupHealthChanged` on transitions.
+ * Crypto- and persistence-free: callers classify failures before signalling.
+ *
+ * State is in-memory per-process — a restart re-derives it from the next signal.
+ * Transitions are synchronous (no `await`), so calls cannot interleave; signals
+ * arriving while a rejoin is in flight (`recovering`) are ignored — the recovery
+ * owns the group until it resolves.
+ */ export class GroupHealthMonitor {
+    #emitter;
+    #epochStaleThreshold;
+    #now;
+    #logger;
+    // groupID -> condition -> per-condition state
+    #groups = new Map();
+    // groupID -> epoch ms of the last transition affecting its aggregate state
+    #lastTransitionAt = new Map();
+    constructor(params){
+        this.#emitter = params.emitter;
+        this.#epochStaleThreshold = params.epochStale?.threshold ?? DEFAULT_EPOCH_STALE_THRESHOLD;
+        this.#now = params.now ?? Date.now;
+        this.#logger = params.logger ?? getKubunLogger('group-health-monitor');
+    }
+    /**
+   * Record a failure observation for a condition. Below the condition's
+   * threshold this only increments the counter; on reaching it the group
+   * transitions to `degraded` (emitted once, then latched). Ignored while the
+   * group is `recovering` (the rejoin owns it) or already `degraded`/failed.
+   */ signal(groupID, condition) {
+        const state = this.#ensure(groupID, condition);
+        if (state.phase !== 'healthy') {
+            // non-healthy: further failures are expected, don't re-emit.
+            return;
+        }
+        state.count += 1;
+        if (state.count >= this.#thresholdFor(condition)) {
+            state.phase = 'degraded';
+            this.#stamp(groupID);
+            this.#emit(groupID, condition, 'degraded');
+        }
+    }
+    /**
+   * Clear a condition to healthy and re-arm (counter reset), driven by the
+   * success path. Silent: only recovery (via the mark* methods) is surfaced.
+   */ reset(groupID, condition) {
+        const state = this.#ensure(groupID, condition);
+        state.count = 0;
+        if (state.phase !== 'healthy') {
+            state.phase = 'healthy';
+            this.#stamp(groupID);
+        }
+    }
+    markRecovering(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.phase = 'recovering';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovering');
+    }
+    /** Emit the transient `recovered` event, then settle the phase to `healthy`. */ markRecovered(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.count = 0;
+        state.phase = 'healthy';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovered');
+    }
+    /** Leave the group `recovery-failed` until a later success resets it. */ markRecoveryFailed(groupID) {
+        const state = this.#ensure(groupID, 'epoch-stale');
+        state.phase = 'recovery-failed';
+        this.#stamp(groupID);
+        this.#emit(groupID, 'epoch-stale', 'recovery-failed');
+    }
+    /** Aggregate state: the first non-healthy condition phase, else `healthy`. */ getState(groupID) {
+        const conditions = this.#groups.get(groupID);
+        if (conditions == null) {
+            return 'healthy';
+        }
+        for (const state of conditions.values()){
+            if (state.phase !== 'healthy') {
+                return state.phase;
+            }
+        }
+        return 'healthy';
+    }
+    getHealth(groupID) {
+        return {
+            state: this.getState(groupID),
+            lastTransitionAt: this.#lastTransitionAt.get(groupID) ?? null
+        };
+    }
+    #stamp(groupID) {
+        this.#lastTransitionAt.set(groupID, this.#now());
+    }
+    #thresholdFor(condition) {
+        // Only `epoch-stale` exists today; switch when more conditions land.
+        return condition === 'epoch-stale' ? this.#epochStaleThreshold : Number.POSITIVE_INFINITY;
+    }
+    #ensure(groupID, condition) {
+        let conditions = this.#groups.get(groupID);
+        if (conditions == null) {
+            conditions = new Map();
+            this.#groups.set(groupID, conditions);
+        }
+        let state = conditions.get(condition);
+        if (state == null) {
+            state = {
+                phase: 'healthy',
+                count: 0
+            };
+            conditions.set(condition, state);
+        }
+        return state;
+    }
+    #emit(groupID, condition, state) {
+        // Enkaku's `emit` rethrows a throwing subscriber; catch so it can't leak an
+        // unhandled rejection.
+        this.#emitter.emit('groupHealthChanged', {
+            groupID,
+            condition,
+            state
+        }).catch((error)=>{
+            this.#logger.error('groupHealthChanged listener failed', {
+                groupID,
+                condition,
+                state,
+                error
+            });
+        });
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { StoreProvider } from '@kubun/db';
+import { HLC } from '@kubun/hlc';
+import { type Logger } from '@kubun/logger';
+import type { GroupMLS } from '@kumiai/rpc';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+export type CreateGroupMLSParams = {
+    /** Single canonical access point for the device's MLS `GroupHandle`. */
+    registry: GroupHandleRegistry;
+    /**
+     * Store coordinator used to open the receive-side commit transaction so the
+     * MLS ratchet advance and the roster delta writes commit (or roll back)
+     * together. Without one transaction, a roster-write failure after the ratchet
+     * persists would silently keep a removed member's writes applying.
+     */
+    stores: StoreProvider;
+    /**
+     * Device-wide monotonic clock for stamping the `removed_at_hlc` of members
+     * dropped (and the `hlc` of members added) by a received MLS Commit. Pass the
+     * engine's single instance so every write from this device advances one shared
+     * clock, preventing two same-millisecond writes from minting identical
+     * timestamps (the second would silently lose under last-writer-wins).
+     */
+    hlc: HLC;
+    groupID: string;
+    logger?: Logger;
+};
+/**
+ * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
+ * {@link GroupMLS} lifecycle port: apply received Commits to advance the epoch,
+ * export GroupInfo for a recovery responder, and expose the epoch-independent
+ * recovery seed. group-rpc owns the transport + orchestration (subscribe the
+ * non-rotating handshake topic, run these methods, resync the app lane when the
+ * epoch advances); this adapter owns the MLS state, storage, and atomicity.
+ */
+export declare function createGroupMLS(params: CreateGroupMLSParams): GroupMLS;