@kubun/plugin-p2p 0.11.0 → 0.12.0

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

@@ -3,6 +3,14 @@ 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.
  *
@@ -13,17 +21,38 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
  *
  * 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`.
+ * 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
@@ -34,31 +63,26 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
    * 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.
+   * 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);
-            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;
+            return {
+                result,
+                persist: true
+            };
         });
     }
     /**
@@ -72,7 +96,10 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
    * use `withHandle`, which persists the advanced state.
    */ readHandle(groupID, fn, options) {
         return this.#withLockedHandle(groupID, options, async (entry)=>{
-            return await fn(entry.handle);
+            return {
+                result: await fn(entry.handle),
+                persist: false
+            };
         });
     }
     /**
@@ -87,13 +114,15 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
         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;
+            return {
+                result,
+                persist: true
+            };
         });
     }
     /**
@@ -109,68 +138,316 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
    * 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) {
+   * 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);
+                const workingHandle = await this.#restore(tx, groupID, options);
                 const { result, updated } = await fn(workingHandle, tx);
                 await this.#persist(tx, groupID, updated);
-                tx.onCommit(()=>this.invalidate(groupID));
+                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, 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) {
+   * 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;
-        const entry = this.#getOrCreateEntry(groupID);
-        return entry.mutex.run(async ()=>{
-            if (entry.handle == null) {
-                entry.handle = await this.#restore(stores, groupID);
+        // 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;
             }
-            return fn(entry, stores);
-        });
+            // 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;
-            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));
+            return {
+                result: undefined,
+                persist: true
+            };
         });
     }
     /**
@@ -187,9 +464,9 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
    * `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 { groupID, handle, stores, replace } = params;
         const existing = this.#entries.get(groupID);
-        if (existing?.handle != null) {
+        if (existing?.handle != null && replace !== true) {
             throw new Error(`GroupHandleRegistry.seed: handle already cached for group ${groupID}`);
         }
         const serialized = serializeMLSGroupState(handle);
@@ -197,9 +474,14 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
         await p2pStore.saveMLSState(toMLSStateInsert(serialized, groupID, this.#deviceID));
         stores.onCommit(()=>{
             const entry = this.#getOrCreateEntry(groupID);
-            if (entry.handle == null) {
+            // 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) {
@@ -213,7 +495,7 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
         }
         return entry;
     }
-    async #restore(stores, groupID) {
+    async #restore(stores, groupID, options) {
         const p2pStore = await getP2PStore(stores);
         const row = await p2pStore.getMLSState(groupID, this.#deviceID);
         if (row == null) {
@@ -228,7 +510,15 @@ import { fromMLSStateRow, serializeMLSGroupState, toMLSStateInsert } from './mls
             deviceID: this.#deviceID,
             epoch: row.epoch
         });
-        return await restoreMLSGroupHandle(fromMLSStateRow(row));
+        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);

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

@@ -1,14 +1,15 @@
 import type { ProcedureHandlers } from '@enkaku/server';
 import type { ProcessBroadcastParams } from './broadcast.js';
-import type { ControlProtocol, SyncProtocol } from './group-protocols.js';
+import type { ControlProtocol, PeerProtocol, 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.
+ * 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.