@kubun/plugin-p2p 0.10.1 → 0.12.0

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

@@ -1 +1,533 @@
-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 n}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.#n(e);return i.mutex.run(async()=>(null==i.handle&&(i.handle=await this.#l(s,e)),r(i,s)))}invalidate(e){this.#s.delete(e)}replaceHandle(e,t,r){return this.#i(e,r,async(r,s)=>{r.handle=t,await this.#a(s,e,t)})}async seed(e){let{groupID:r,handle:s,stores:i}=e,l=this.#s.get(r);if(l?.handle!=null)throw Error(`GroupHandleRegistry.seed: handle already cached for group ${r}`);let o=a(s),h=await t(i);await h.saveMLSState(n(o,r,this.#t)),i.onCommit(()=>{let e=this.#n(r);null==e.handle&&(e.handle=s)})}#n(e){let t=this.#s.get(e);return null==t&&(t={handle:null,mutex:r()},this.#s.set(e,t)),t}async #l(e,r){let a=await t(e),n=await a.getMLSState(r,this.#t);if(null==n)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:n.epoch}),await s(i(n))}async #a(e,r,s){let i=a(s),l=await t(e);await l.saveMLSState(n(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';
+/**
+ * The backstop deadline on acquiring a group's handle.
+ *
+ * Every hold is in-memory work bounded by one MLS operation — microseconds to
+ * milliseconds — so 15 s is not a budget, it is the point past which the only
+ * remaining explanation is a lock-order bug. Exceeding it fails the waiting
+ * operation, which releases whatever the waiter held and lets the holder finish.
+ */ const MUTEX_ACQUIRE_TIMEOUT_MS = 15_000;
+/**
+ * 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.
+ */ export class GroupHandleRegistry {
+    #stores;
+    #deviceID;
+    #logger;
+    #entries = new Map();
+    // Last epoch this registry OBSERVED on a group's handle, published for
+    // synchronous readers. Deliberately a SEPARATE map from `#entries`: the
+    // transactional advance path swaps the durable row and then `invalidate`s the
+    // cached handle, so an epoch stored on the entry would be thrown away by the
+    // very operation that advanced it — which is exactly how a reader ends up
+    // answering a pre-commit epoch forever.
+    #epochs = new Map();
+    // Notified when a published epoch changes — see `onEpochChanged`.
+    #epochListeners = new Set();
+    #mutexTimeoutMs;
+    // Snapshots numbered in mutex order, and the highest number already written /
+    // already published. All three exist because the persist and the epoch publish
+    // happen after the lock is released — see `#persistOrdered`.
+    #stateSequence = new Map();
+    #persistedSequence = new Map();
+    #publishedSequence = new Map();
+    // How many times each group's cache has been dropped, and the restore each
+    // group currently has in flight. Both exist because restores run outside the
+    // mutex — see `#withLockedHandle`.
+    #generations = new Map();
+    #restoring = new Map();
+    constructor(params){
+        this.#stores = params.stores;
+        this.#deviceID = params.deviceID;
+        this.#logger = params.logger ?? getKubunLogger('plugin-p2p:group-handle-registry');
+        this.#mutexTimeoutMs = params.mutexTimeoutMs ?? MUTEX_ACQUIRE_TIMEOUT_MS;
+    }
+    /**
+   * 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: under a caller transaction that commits later, the mutex releases
+   * before that commit, so a concurrent same-group op can observe the uncommitted
+   * handle. `onRollback` repairs the cache; the live exposure is a cross-epoch
+   * decrypt that fails the MLS check and skips its persist — a dropped message,
+   * never a durable divergence, and only on a multi-connection adapter. Use
+   * `withHandleReplacingInTransaction` to avoid the window entirely.
+   *
+   * The persist runs AFTER the mutex is released — see {@link #withLockedHandle}
+   * — but is still awaited here, so a caller that returns has its state durable.
+   */ withHandle(groupID, fn, options) {
+        return this.#withLockedHandle(groupID, options, async (entry, stores)=>{
+            const result = await fn(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,
+                persist: true
+            };
+        });
+    }
+    /**
+   * 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 {
+                result: await fn(entry.handle),
+                persist: false
+            };
+        });
+    }
+    /**
+   * 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;
+            // 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,
+                persist: true
+            };
+        });
+    }
+    /**
+   * 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.
+   *
+   * The lock MUST span the commit: the `onCommit` invalidation then fires while it
+   * is still held, so there is no post-mutex / pre-commit window for a concurrent
+   * op to clobber the advance.
+   *
+   * The working handle MUST be fresh, not the cached one: `processMessage` advances
+   * the ratchet IN PLACE, so running against the cache would advance it while the
+   * transaction is still uncommitted, and a rollback would leave the cache ahead of
+   * the reverted DB row. Costs one extra MLS-state restore per call.
+   *
+   * THE ONE PATH that still touches the database under the mutex, because its
+   * whole contract is that the lock spans the commit. It is therefore the only
+   * remaining candidate to be the holder in a lock-order cycle — see
+   * {@link #withLockedHandle} for why that matters — and the acquisition
+   * deadline on every other caller is what stops such a cycle being permanent.
+   */ async withHandleReplacingInTransaction(groupID, stores, fn, options) {
+        const entry = this.#getOrCreateEntry(groupID);
+        return entry.mutex.run(async ()=>{
+            return await stores.withTransaction(async (tx)=>{
+                const workingHandle = await this.#restore(tx, groupID, options);
+                const { result, updated } = await fn(workingHandle, tx);
+                await this.#persist(tx, groupID, updated);
+                tx.onCommit(()=>{
+                    // Publish the advance BEFORE dropping the cached handle. This is the
+                    // receive path: applying someone else's commit is the one way a
+                    // device's epoch moves without it ever sealing anything, so if the
+                    // advance is not published here nothing else republishes it and every
+                    // later commit is classified against a pre-commit number. Inside
+                    // `onCommit` because the row is only then durable — a rollback must
+                    // leave the published epoch where it was.
+                    this.#publishEpoch(groupID, updated);
+                    this.invalidate(groupID);
+                });
+                return result;
+            });
+        }, this.#acquireOptions(groupID));
+    }
+    /**
+   * Shared prelude: resolve stores, get-or-create entry, restore the handle if
+   * the cache is empty, run `fn` under the per-group mutex, then persist.
+   * Centralizes lock/restore semantics so `withHandle` and
+   * `withHandleReplacing` cannot drift.
+   *
+   * **The database is never touched while the mutex is held** — restore before
+   * the lock, persist after. Kysely's SQLite dialect has one connection, so a
+   * query issued while a transaction is open queues with no timeout, and every
+   * `request*` control mutation holds that connection while waiting for this
+   * mutex. A holder waiting on the connection in return wedged the group for the
+   * life of the process. See `group-mutex-db-deadlock.test.ts`.
+   *
+   * The persist is still awaited by the caller, so durability is unchanged.
+   */ async #withLockedHandle(groupID, options, fn) {
+        const stores = options?.stores ?? this.#stores;
+        // Restoring outside the lock costs a re-read when an applied commit
+        // invalidates while this call queues; the generation counter detects that.
+        //
+        // Bounded by TIME, not attempts: `walkCommits` invalidates once per applied
+        // commit, so a count bound turns an ordinary catch-up burst into a throw for
+        // anything reading alongside it. Each pass waits on a real acquisition and a
+        // real row read, so there is nothing to spin on.
+        const deadline = Date.now() + this.#mutexTimeoutMs;
+        for(let attempt = 0;; attempt++){
+            const entry = this.#getOrCreateEntry(groupID);
+            const generation = this.#generation(groupID);
+            const restored = entry.handle == null ? await this.#restoreShared(stores, groupID, generation) : undefined;
+            const outcome = await entry.mutex.run(async ()=>{
+                if (this.#generation(groupID) !== generation || this.#entries.get(groupID) !== entry) {
+                    // The cache was dropped while this call queued for the lock.
+                    // Anything read before that is stale, and this entry is no longer
+                    // the one the registry hands out.
+                    return {
+                        retry: true
+                    };
+                }
+                if (entry.handle == null) {
+                    if (restored == null) {
+                        return {
+                            retry: true
+                        };
+                    }
+                    entry.handle = restored;
+                }
+                const { result, persist } = await fn(entry, stores);
+                // Read AFTER `fn`, still under the mutex: `withHandleReplacing`
+                // rebinds `entry.handle`, and `withHandle` may have advanced it in
+                // place. Skipped on throw — a callback that failed left no state worth
+                // publishing, and the next successful operation republishes.
+                const snapshot = entry.handle;
+                // Numbered under the lock: the only place snapshot order is defined.
+                // Numbering at the persist would number them in whatever order the
+                // released callers arrived, letting an older claim to be newer.
+                const sequence = (this.#stateSequence.get(groupID) ?? 0) + 1;
+                this.#stateSequence.set(groupID, sequence);
+                return {
+                    retry: false,
+                    result,
+                    snapshot,
+                    persist,
+                    sequence
+                };
+            }, this.#acquireOptions(groupID));
+            if (outcome.retry) {
+                if (Date.now() >= deadline) {
+                    throw new Error(`Group ${groupID} handle could not be held: its cache was invalidated ${attempt + 1} times in ${this.#mutexTimeoutMs}ms, each time before this call could take the lock`);
+                }
+                continue;
+            }
+            // Epoch-change listeners read the PERSISTED row (the app lane re-exports
+            // its anchor from it), so an epoch published ahead of its row puts the
+            // announce on a topic nobody listens to.
+            //
+            // A non-persisting op therefore must NOT publish: `readHandle` snapshots
+            // the entry a writer just advanced in place and has nothing to await, so
+            // it would publish ahead of that writer's row and claim the sequence
+            // number that then suppresses the writer's own publish.
+            if (outcome.persist) {
+                await this.#persistOrdered(stores, groupID, outcome.snapshot, outcome.sequence);
+                this.#publishOrdered(groupID, outcome.snapshot, outcome.sequence);
+            } else if (this.#epochs.get(groupID) === undefined) {
+                // Except a first observation, which notifies nobody but must be recorded
+                // — otherwise the next advance reads as the first one and is swallowed.
+                this.#publishOrdered(groupID, outcome.snapshot, outcome.sequence);
+            }
+            return outcome.result;
+        }
+    }
+    /**
+   * Turns a residual lock-order bug into one failed operation instead of a dead
+   * group: the waiter giving up closes its own transaction, so the holder
+   * proceeds and the group recovers without an app restart.
+   */ #acquireOptions(groupID) {
+        return {
+            acquireTimeoutMs: this.#mutexTimeoutMs,
+            acquireTimeoutError: ()=>{
+                this.#logger.error('group handle lock not acquired', {
+                    groupID,
+                    deviceID: this.#deviceID,
+                    timeoutMs: this.#mutexTimeoutMs
+                });
+                return new Error(`Group ${groupID} handle is locked: no operation released it within ${this.#mutexTimeoutMs}ms`);
+            }
+        };
+    }
+    /**
+   * Publish outside the mutex without an older snapshot republishing over a
+   * newer one. `#publishEpoch` is deliberately non-monotonic — a rolled-back
+   * advance republishes the LOWER epoch — so only the sequence can say which
+   * snapshot is later.
+   */ #publishOrdered(groupID, handle, sequence) {
+        if ((this.#publishedSequence.get(groupID) ?? 0) > sequence) {
+            return;
+        }
+        this.#publishedSequence.set(groupID, sequence);
+        this.#publishEpoch(groupID, handle);
+    }
+    /**
+   * Persist outside the mutex without a stale snapshot landing on a fresher one.
+   * A lower sequence is strictly older state; skipping it is safe because it is
+   * a prefix of what the fresher row already says. A single-connection adapter
+   * keeps issue order, a multi-connection one need not.
+   */ async #persistOrdered(stores, groupID, handle, sequence) {
+        if ((this.#persistedSequence.get(groupID) ?? 0) > sequence) {
+            return;
+        }
+        await this.#persist(stores, groupID, handle);
+        if ((this.#persistedSequence.get(groupID) ?? 0) < sequence) {
+            this.#persistedSequence.set(groupID, sequence);
+        }
+    }
+    /**
+   * The last epoch this registry observed for `groupID`, or `null` if it has
+   * never held a handle for it. Synchronous, because the one port that needs it
+   * — `GroupCrypto.epoch()` — is synchronous by contract while every handle
+   * access here is async and mutex-guarded.
+   *
+   * Publishes a NUMBER, never the handle: a scalar cannot advance a ratchet, skip
+   * the per-group mutex, or mutate MLS state. DO NOT widen this to return the
+   * handle — the mutex is what makes the ratchet advance and its row write one
+   * atomic step.
+   *
+   * Deliberately NOT monotonic: a rolled-back advance must republish the LOWER
+   * epoch, or the reader is pinned above the state the device holds. Genuine
+   * backwards installs are refused upstream, by `replaceHandle`'s epoch guard and
+   * `saveMLSState`'s no-op on a lower row.
+   */ groupEpoch(groupID) {
+        return this.#epochs.get(groupID) ?? null;
+    }
+    /**
+   * Called when the epoch published for a group CHANGES — an advance, or the
+   * lower republish a rolled-back one produces. Returns the unsubscribe.
+   *
+   * The first observation of a group is deliberately NOT a change: restoring a
+   * handle at boot publishes an epoch where there was none, and treating that as
+   * a rotation would have every group fire its epoch-change consumers once per
+   * process start.
+   *
+   * Listeners run INSIDE the per-group mutex and inside whatever transaction the
+   * advancing operation holds, so one must never await the registry or the store
+   * from here. Defer the work.
+   */ onEpochChanged(listener) {
+        this.#epochListeners.add(listener);
+        return ()=>{
+            this.#epochListeners.delete(listener);
+        };
+    }
+    #publishEpoch(groupID, handle) {
+        const epoch = Number(handle.epoch);
+        const previous = this.#epochs.get(groupID);
+        this.#epochs.set(groupID, epoch);
+        if (previous === undefined || previous === epoch) {
+            return;
+        }
+        for (const listener of this.#epochListeners){
+            try {
+                listener(groupID, epoch);
+            } catch (error) {
+                // A consumer that throws must not fail the operation that advanced the
+                // epoch: the handle is already swapped and its row already written.
+                this.#logger.warn('epoch-change listener threw', {
+                    groupID,
+                    epoch,
+                    error
+                });
+            }
+        }
+    }
+    /**
+   * 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.
+   *
+   * The published epoch is deliberately LEFT in place. Invalidation is how this
+   * registry says "re-read the durable row", not "this device no longer has an
+   * epoch" — and the transactional advance path invalidates immediately after
+   * committing an advance, so clearing here would discard the newest epoch the
+   * device has. The next restore republishes whatever the row actually holds.
+   */ invalidate(groupID) {
+        this.#entries.delete(groupID);
+        // Bumped so a restore already in flight — they run outside the mutex now —
+        // knows the row it read has been superseded and must not be installed. See
+        // {@link #withLockedHandle}.
+        this.#generations.set(groupID, this.#generation(groupID) + 1);
+    }
+    /** How many times this group's cache has been dropped. */ #generation(groupID) {
+        return this.#generations.get(groupID) ?? 0;
+    }
+    /**
+   * Restore, sharing one read between callers that arrive together — but only
+   * through the SAME provider. A caller inside a transaction must not join a
+   * device-wide read: that read queues behind its own open transaction, so it
+   * would be waiting on itself.
+   */ #restoreShared(stores, groupID, generation) {
+        const inFlight = this.#restoring.get(groupID);
+        if (inFlight != null) {
+            // Generation matters as much as the provider: a read started before a
+            // commit returns the pre-commit row, and a caller arriving after that
+            // commit would adopt it with its own generation check satisfied.
+            return inFlight.stores === stores && inFlight.generation === generation ? inFlight.promise : this.#restore(stores, groupID);
+        }
+        const promise = this.#restore(stores, groupID);
+        this.#restoring.set(groupID, {
+            stores,
+            generation,
+            promise
+        });
+        void promise.finally(()=>{
+            if (this.#restoring.get(groupID)?.promise === promise) {
+                this.#restoring.delete(groupID);
+            }
+        })// A group with no MLS state rejects here, which is ordinary; the caller
+        // handles the rejection it was handed, and this cleanup branch must not
+        // surface a second, unhandled one.
+        .catch(()=>{});
+        return promise;
+    }
+    /**
+   * 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.
+   *
+   * MONOTONIC in the epoch: a handle strictly BEHIND the one held is refused, no
+   * cache swap and no persist. Installing one would roll this device's key schedule
+   * back and have it encrypt at an epoch its co-members have left, producing traffic
+   * nobody can open with nothing raised. Reachable because a journalled commit is
+   * adopted at-least-once, carrying a handle frozen at the epoch it was built.
+   *
+   * The bound is STRICT — a same-epoch re-install must still win, because decrypting
+   * an application message advances the secret-tree generation within one epoch.
+   */ replaceHandle(groupID, handle, options) {
+        return this.#withLockedHandle(groupID, options, async (entry, stores)=>{
+            const held = entry.handle;
+            if (held != null && handle.epoch < held.epoch) {
+                this.#logger.warn('replaceHandle: refused a handle behind the one held', {
+                    groupID,
+                    deviceID: this.#deviceID,
+                    heldEpoch: Number(held.epoch),
+                    offeredEpoch: Number(handle.epoch)
+                });
+                return {
+                    result: undefined,
+                    persist: false
+                };
+            }
+            entry.handle = 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));
+            return {
+                result: undefined,
+                persist: true
+            };
+        });
+    }
+    /**
+   * 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, replace } = params;
+        const existing = this.#entries.get(groupID);
+        if (existing?.handle != null && replace !== true) {
+            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);
+            // A rejoin installs its handle over the stale one; anything else keeps
+            // whatever is already there. Assigning unconditionally would let a second
+            // Welcome delivery roll a live member back, which is what the guard above
+            // refuses on the other path.
+            if (entry.handle == null || replace === true) {
+                entry.handle = handle;
+            }
+            this.#publishEpoch(groupID, entry.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, options) {
+        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({
+            serialized: fromMLSStateRow(row),
+            ...options?.resolveLedgerEntries != null ? {
+                resolveLedgerEntries: options.resolveLedgerEntries
+            } : {},
+            ...options?.onLedgerEntries != null ? {
+                onLedgerEntries: options.onLedgerEntries
+            } : {}
+        });
+    }
+    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,30 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { ProcessBroadcastParams } from './broadcast.js';
+import type { ControlProtocol, PeerProtocol, SyncProtocol } from './group-protocols.js';
+/**
+ * The 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>;
+    peer: ProcedureHandlers<PeerProtocol>;
+};
+/**
+ * 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;