@kubun/plugin-p2p 0.10.1 → 0.11.0

package/lib/groups/circle-reducers.js

@@ -0,0 +1,198 @@
+import { normalizeDID } from '@kokuin/token';
+import { foldAdminRoster } from './admin-roster.js';
+/** Ledger entry `type` for a circle-membership claim. */ export const CIRCLE_MEMBER_ENTRY_TYPE = 'circle.member';
+function isRemovedValue(value) {
+    return 'removed' in value && value.removed === true;
+}
+/**
+ * Deterministic composite subject for a circle member. The signed entry's
+ * `subject` encodes both the circle and the member, so the ledger's `subject`
+ * column uniquely identifies the pair and per-member LWW ordering + dedup work
+ * without consulting the value.
+ *
+ * Unambiguous because the member is a normalized DID (`did:method:...`), which
+ * never contains the `/member:` separator: every reachable separator therefore
+ * sits between the circle id and the DID, and the decoder splits on the last
+ * one. The labeled `circle:` / `/member:` prefixes also keep the encoding
+ * distinct from any other reducer's subject scheme.
+ */ export function encodeCircleMemberSubject(circleID, memberDID) {
+    return `circle:${circleID}/member:${normalizeDID(memberDID)}`;
+}
+const SUBJECT_PREFIX = 'circle:';
+const MEMBER_SEPARATOR = '/member:';
+/** Tolerant inverse of {@link encodeCircleMemberSubject}: null on a malformed subject. */ export function decodeCircleMemberSubject(subject) {
+    if (!subject.startsWith(SUBJECT_PREFIX)) {
+        return null;
+    }
+    const separator = subject.lastIndexOf(MEMBER_SEPARATOR);
+    if (separator === -1) {
+        return null;
+    }
+    const circleID = subject.slice(SUBJECT_PREFIX.length, separator);
+    const memberDID = subject.slice(separator + MEMBER_SEPARATOR.length);
+    if (circleID.length === 0 || memberDID.length === 0) {
+        return null;
+    }
+    return {
+        circleID,
+        memberDID
+    };
+}
+/**
+ * Per-member last-writer-wins circle roster. {@link foldLedger} sorts by the
+ * total order `(hlc, entryID)`, so each subject's highest-ordered entry is
+ * applied last and decides the outcome: an active value sets the member with its
+ * role, a tombstone removes them. Whole-value replacement means add / remove /
+ * re-add converge to the same state on every peer regardless of arrival order.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC so a key authorized when it wrote stays authorized even after a later
+ * revoke. The gate is the ledger admin-fold ONLY — membership and MLS-removal
+ * are enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */ export function createCircleMemberReducer(isAdminAtHLC) {
+    return {
+        type: CIRCLE_MEMBER_ENTRY_TYPE,
+        seed: ()=>({
+                members: new Map()
+            }),
+        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
+        apply: (verified, state)=>{
+            const members = new Map(state.members);
+            const { subject, value } = verified.entry;
+            if (isRemovedValue(value)) {
+                members.delete(subject);
+                return {
+                    members
+                };
+            }
+            const decoded = decodeCircleMemberSubject(subject);
+            if (decoded == null) {
+                // Malformed subject: leave the map untouched rather than guess the pair.
+                return state;
+            }
+            members.set(subject, {
+                circleID: decoded.circleID,
+                memberDID: decoded.memberDID,
+                role: value.role
+            });
+            return {
+                members
+            };
+        }
+    };
+}
+/** Ledger entry `type` for a circle definition (create / update / delete). */ export const CIRCLE_DEF_ENTRY_TYPE = 'circle.def';
+function isRemovedDef(value) {
+    return 'removed' in value && value.removed === true;
+}
+/**
+ * Per-circle last-writer-wins definition. The signed entry's `subject` is the
+ * circleID directly, so no decode is needed. {@link foldLedger} sorts by the
+ * total order `(hlc, entryID)`, so each circle's highest-ordered entry is
+ * applied last and decides the outcome: an active value sets the definition, a
+ * tombstone deletes it. Whole-value replacement means create / update / delete
+ * converge to the same state on every peer regardless of arrival order.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
+ * enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */ export function createCircleDefReducer(isAdminAtHLC) {
+    return {
+        type: CIRCLE_DEF_ENTRY_TYPE,
+        seed: ()=>({
+                circles: new Map()
+            }),
+        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
+        apply: (verified, state)=>{
+            const circles = new Map(state.circles);
+            const { subject, value } = verified.entry;
+            if (isRemovedDef(value)) {
+                circles.delete(subject);
+                return {
+                    circles
+                };
+            }
+            circles.set(subject, {
+                name: value.name,
+                description: value.description,
+                catalogIDs: value.catalogIDs
+            });
+            return {
+                circles
+            };
+        }
+    };
+}
+/** Ledger entry `type` for a group-settings claim. */ export const GROUP_SETTINGS_ENTRY_TYPE = 'group.settings';
+/**
+ * Per-field last-writer-wins group settings. The signed entry's `subject` is the
+ * groupID directly, so no decode is needed. {@link foldLedger} sorts by the total
+ * order `(hlc, entryID)` and applies low→high, so for each field the
+ * highest-ordered entry that SETS that field wins naturally.
+ *
+ * This reducer merges per field rather than replacing the whole value the way
+ * `circle.def` / `circle.member` do: those project a single cohesive record
+ * where add / remove / re-add must converge to one state, so whole-value
+ * replacement is correct. Group settings instead accumulate independent fields
+ * (`name`, `description`) that different entries touch in isolation, so a
+ * name-only update must not clobber a previously-set description. Presence is
+ * decided by `value.field !== undefined` rather than `'field' in value`: an
+ * explicit `undefined` is treated as "not set" (no change), while `''` is a real
+ * value that clears the field.
+ *
+ * Authority is the injected `isAdminAtHLC`, evaluated against the entry's own
+ * HLC. The gate is the ledger admin-fold ONLY — membership and MLS-removal are
+ * enforced outside this projection — so the fold remains synchronous and
+ * deterministic from the ledger alone.
+ */ export function createGroupSettingsReducer(isAdminAtHLC) {
+    return {
+        type: GROUP_SETTINGS_ENTRY_TYPE,
+        seed: ()=>({
+                settings: new Map()
+            }),
+        verifyAuthority: (verified)=>isAdminAtHLC(verified.issuer, verified.entry.hlc),
+        apply: (verified, state)=>{
+            const settings = new Map(state.settings);
+            const { subject, value } = verified.entry;
+            const prior = settings.get(subject) ?? {};
+            const next = {
+                ...prior
+            };
+            if (value.name !== undefined) {
+                next.name = value.name;
+            }
+            if (value.description !== undefined) {
+                next.description = value.description;
+            }
+            settings.set(subject, next);
+            return {
+                settings
+            };
+        }
+    };
+}
+/**
+ * Build an {@link IsAdminAtHLC} predicate from the group's verified admin-role
+ * ledger entries. It re-folds the admin sub-ledger at each queried entry's HLC,
+ * so the answer is rotation-aware (was-admin-at-HLC, not is-admin-now): a key
+ * granted admin at HLC h authorizes entries at or after h, and a later revoke
+ * stops authorizing entries from that point on. `foldAdminRoster`'s `atHLC`
+ * compare is inclusive (`entry.hlc <= atHLC`), so an entry at exactly the grant
+ * HLC sees the grant and is authorized, and an entry at exactly the revoke HLC
+ * sees the revoke and is not.
+ *
+ * Callers load the verified admin entries once (via `loadVerifiedAdminEntries`)
+ * and reuse the returned predicate across the circle / def / settings folds.
+ *
+ * Authority here is ledger-admin-only: it answers "did the ledger grant this
+ * issuer admin at this HLC?" and does NOT check the issuer's MLS membership at
+ * that HLC. So an admin who was removed from the MLS group but whose admin role
+ * was never revoked on the ledger still has authorizing entries folded in.
+ * Closing that requires removal to write a ledger revocation atomically with the
+ * MLS-roster delta (the same MLS-commit/roster atomicity work that keeps a
+ * removed member's writes from applying); it is deliberately out of scope here.
+ */ export function adminAuthorityFromEntries(adminEntries, anchor) {
+    return (issuer, hlc)=>foldAdminRoster(adminEntries, anchor, hlc).admins.has(normalizeDID(issuer));
+}

package/lib/groups/events.d.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from '@enkaku/event';
+import { EventEmitter } from '@sozai/event';
 import type { CircleData, CircleMemberData, DelegationData, GroupData, GroupHealthData, GroupMemberData, RevokedDelegationData } from '../types.js';
 export type P2PEventMap = {
     groupJoined: GroupData;
@@ -14,6 +14,10 @@ export type P2PEventMap = {
     groupMemberLeft: GroupMemberData & {
         groupID: string;
     };
+    /** A member's group role was promoted to or demoted from admin via the ledger. */
+    groupMemberRoleChanged: GroupMemberData & {
+        groupID: string;
+    };
     /**
      * A member announced a voluntary leave (received `group:leaveRequest`).
      * Advisory: MLS forbids self-removal, so the leaf lingers until an admin

package/lib/groups/events.js

@@ -1 +1,10 @@
-import{EventEmitter as e}from"@enkaku/event";import{fromEmitter as r}from"@enkaku/generator";export function createP2PEventEmitter(){return new e}export function createFilteredGenerator(e,t,n){return r(e,t,{filter:n})}
+import { EventEmitter } from '@sozai/event';
+import { fromEmitter } from '@sozai/generator';
+export function createP2PEventEmitter() {
+    return new EventEmitter();
+}
+export function createFilteredGenerator(emitter, eventName, filter) {
+    return fromEmitter(emitter, eventName, {
+        filter
+    });
+}

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

@@ -0,0 +1,63 @@
+import { type Capabilities, type GroupContextExtension, type GroupHandle, type IncomingMessageCallback } from '@kumiai/mls';
+/**
+ * MLS GroupContext extension type carrying the genesis anchor. A uint16 outside
+ * the MLS default extension types (1–5) and clear of every reserved GREASE
+ * value, so it can never collide with a ts-mls built-in or a probing extension.
+ */
+export declare const GROUP_ANCHOR_EXTENSION_TYPE = 61696;
+/**
+ * Genesis anchor baked into the MLS GroupContext at group creation: the creator
+ * DID is the epoch-0 admin. It survives every epoch and is authenticated by the
+ * GroupInfo signature, so every joiner reads the same value. Treated as
+ * immutable for the lifetime of the group.
+ */
+export type GroupAnchor = {
+    creatorDID: string;
+    version: number;
+    /**
+     * Base64 of 32 cryptographically-random bytes minted once at group creation.
+     * It is the epoch-independent seed for the non-rotating handshake/recovery
+     * topic: baked into the MLS GroupContext, authenticated by the GroupInfo
+     * signature, so every member on every epoch derives the same rendezvous and a
+     * peer stranded on a stale epoch can always rejoin. Immutable for the group's
+     * whole life.
+     */
+    recoverySecret: string;
+};
+export declare function encodeGroupAnchor(anchor: GroupAnchor): Uint8Array;
+/**
+ * Tolerant decode: returns null on malformed bytes or wrong shape. The
+ * `recoverySecret` is required and must be a non-empty string — an anchor
+ * without it cannot seed the recovery rendezvous, so a missing/empty value is a
+ * malformed anchor, not a tolerated absence.
+ */
+export declare function decodeGroupAnchor(bytes: Uint8Array): GroupAnchor | null;
+export declare function buildGroupAnchorExtension(anchor: GroupAnchor): GroupContextExtension;
+export declare function buildCurrentGroupAnchorExtension(creatorDID: string, recoverySecret: string): GroupContextExtension;
+/**
+ * Leaf-node capabilities advertising the genesis-anchor extension. RFC 9420
+ * requires every member leaf to advertise each custom GroupContext extension
+ * type, or `commitInvite` rejects the added leaf. Pass these at both
+ * `createGroup` (creator leaf) and `createKeyPackageBundle` (invitee leaf) so an
+ * anchored group can be joined.
+ */
+export declare function groupAnchorCapabilities(): Capabilities;
+/**
+ * Commit policy enforcing genesis-anchor immutability. The anchor lives in the
+ * GroupContext extensions and is written once at group creation; kubun issues no
+ * group-context-extensions proposal through any normal path, so any incoming
+ * commit or proposal carrying one is anomalous and is refused before it can
+ * alter the anchor. Refine to inspect the specific extension type if a future
+ * feature legitimately mutates non-anchor group-context extensions.
+ */
+export declare const anchorImmutabilityPolicy: IncomingMessageCallback;
+/**
+ * Read the genesis anchor from a group handle. Returns null only when the anchor
+ * extension is genuinely absent (a group created before the anchor, or
+ * external). A present-but-undecodable extension is corruption, not absence, and
+ * throws — so the control gate treats it as "anchor unreadable" and fails closed
+ * rather than silently downgrading to the forgeable role-column gate. (The anchor
+ * is kubun-written, frozen by the immutability commit policy, and authenticated
+ * by the GroupInfo signature, so this is a corruption guard, not a forgery path.)
+ */
+export declare function readGroupAnchor(handle: GroupHandle): GroupAnchor | null;

package/lib/groups/group-anchor.js

@@ -0,0 +1,107 @@
+import { defaultCapabilities, defaultProposalTypes, makeCustomExtension } from '@kumiai/mls';
+/**
+ * MLS GroupContext extension type carrying the genesis anchor. A uint16 outside
+ * the MLS default extension types (1–5) and clear of every reserved GREASE
+ * value, so it can never collide with a ts-mls built-in or a probing extension.
+ */ export const GROUP_ANCHOR_EXTENSION_TYPE = 0xf100;
+const CURRENT_VERSION = 1;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function encodeGroupAnchor(anchor) {
+    return encoder.encode(JSON.stringify(anchor));
+}
+/**
+ * Tolerant decode: returns null on malformed bytes or wrong shape. The
+ * `recoverySecret` is required and must be a non-empty string — an anchor
+ * without it cannot seed the recovery rendezvous, so a missing/empty value is a
+ * malformed anchor, not a tolerated absence.
+ */ export function decodeGroupAnchor(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(decoder.decode(bytes));
+    } catch  {
+        return null;
+    }
+    if (parsed == null || typeof parsed !== 'object') {
+        return null;
+    }
+    const record = parsed;
+    if (typeof record.creatorDID !== 'string' || typeof record.version !== 'number') {
+        return null;
+    }
+    if (typeof record.recoverySecret !== 'string' || record.recoverySecret.length === 0) {
+        return null;
+    }
+    return {
+        creatorDID: record.creatorDID,
+        version: record.version,
+        recoverySecret: record.recoverySecret
+    };
+}
+export function buildGroupAnchorExtension(anchor) {
+    return makeCustomExtension({
+        extensionType: GROUP_ANCHOR_EXTENSION_TYPE,
+        extensionData: encodeGroupAnchor(anchor)
+    });
+}
+export function buildCurrentGroupAnchorExtension(creatorDID, recoverySecret) {
+    return buildGroupAnchorExtension({
+        creatorDID,
+        version: CURRENT_VERSION,
+        recoverySecret
+    });
+}
+/**
+ * Leaf-node capabilities advertising the genesis-anchor extension. RFC 9420
+ * requires every member leaf to advertise each custom GroupContext extension
+ * type, or `commitInvite` rejects the added leaf. Pass these at both
+ * `createGroup` (creator leaf) and `createKeyPackageBundle` (invitee leaf) so an
+ * anchored group can be joined.
+ */ export function groupAnchorCapabilities() {
+    const base = defaultCapabilities();
+    return base.extensions.includes(GROUP_ANCHOR_EXTENSION_TYPE) ? base : {
+        ...base,
+        extensions: [
+            ...base.extensions,
+            GROUP_ANCHOR_EXTENSION_TYPE
+        ]
+    };
+}
+/**
+ * Commit policy enforcing genesis-anchor immutability. The anchor lives in the
+ * GroupContext extensions and is written once at group creation; kubun issues no
+ * group-context-extensions proposal through any normal path, so any incoming
+ * commit or proposal carrying one is anomalous and is refused before it can
+ * alter the anchor. Refine to inspect the specific extension type if a future
+ * feature legitimately mutates non-anchor group-context extensions.
+ */ export const anchorImmutabilityPolicy = (incoming)=>{
+    const proposals = incoming.kind === 'commit' ? incoming.proposals : [
+        incoming.proposal
+    ];
+    for (const { proposal } of proposals){
+        if (proposal.proposalType === defaultProposalTypes.group_context_extensions) {
+            return 'reject';
+        }
+    }
+    return 'accept';
+};
+/**
+ * Read the genesis anchor from a group handle. Returns null only when the anchor
+ * extension is genuinely absent (a group created before the anchor, or
+ * external). A present-but-undecodable extension is corruption, not absence, and
+ * throws — so the control gate treats it as "anchor unreadable" and fails closed
+ * rather than silently downgrading to the forgeable role-column gate. (The anchor
+ * is kubun-written, frozen by the immutability commit policy, and authenticated
+ * by the GroupInfo signature, so this is a corruption guard, not a forgery path.)
+ */ export function readGroupAnchor(handle) {
+    const extension = handle.state.groupContext.extensions.find((ext)=>ext.extensionType === GROUP_ANCHOR_EXTENSION_TYPE);
+    if (extension == null) {
+        return null;
+    }
+    const data = extension.extensionData;
+    const anchor = data instanceof Uint8Array ? decodeGroupAnchor(data) : null;
+    if (anchor == null) {
+        throw new Error('group anchor extension present but could not be decoded');
+    }
+    return anchor;
+}

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

@@ -0,0 +1,19 @@
+import type { GroupCrypto } from '@kumiai/rpc';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+/**
+ * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
+ * {@link GroupCrypto} port: epoch number, an epoch-bound topic-derivation
+ * secret, and byte-level encrypt/decrypt over the live MLS handle.
+ *
+ * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle` so they take
+ * the per-group mutex and observe the canonical handle, using the same framing as
+ * `MLSEncryptor` (see `mls-codec.ts`).
+ *
+ * `GroupCrypto.epoch()` is synchronous by contract, but the registry only
+ * exposes the handle behind an async, mutex-guarded `readHandle`. group-rpc
+ * always calls `epoch()` immediately after awaiting `exportSecret()` (see
+ * GroupPeer's epoch rebuild), so `exportSecret` records the epoch it read under
+ * the same lock and `epoch()` returns that cached value — no second, racy lock
+ * acquisition.
+ */
+export declare function createGroupCrypto(registry: GroupHandleRegistry, groupID: string): GroupCrypto;

package/lib/groups/group-crypto.js

@@ -0,0 +1,85 @@
+import { toB64 } from '@sozai/codec';
+import { mlsExporter } from 'ts-mls';
+import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
+// Domain-separation label for the epoch-bound topic-derivation secret. Stable so
+// the exported secret is constant within an epoch and rotates when a commit
+// advances the epoch (MLS re-derives exporterSecret per epoch).
+const TOPIC_SECRET_LABEL = 'kubun/group-rpc/topic';
+// Empty context: the epoch already varies the secret; topic derivation mixes in
+// its own epoch/protocol/scope on top.
+const TOPIC_SECRET_CONTEXT = new Uint8Array(0);
+// 32-byte secret feeds an HKDF-based topic derivation; the length is otherwise
+// unconstrained.
+const TOPIC_SECRET_LENGTH = 32;
+/**
+ * Adapts a `GroupHandleRegistry` group into the `@kumiai/rpc`
+ * {@link GroupCrypto} port: epoch number, an epoch-bound topic-derivation
+ * secret, and byte-level encrypt/decrypt over the live MLS handle.
+ *
+ * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle` so they take
+ * the per-group mutex and observe the canonical handle, using the same framing as
+ * `MLSEncryptor` (see `mls-codec.ts`).
+ *
+ * `GroupCrypto.epoch()` is synchronous by contract, but the registry only
+ * exposes the handle behind an async, mutex-guarded `readHandle`. group-rpc
+ * always calls `epoch()` immediately after awaiting `exportSecret()` (see
+ * GroupPeer's epoch rebuild), so `exportSecret` records the epoch it read under
+ * the same lock and `epoch()` returns that cached value — no second, racy lock
+ * acquisition.
+ */ export function createGroupCrypto(registry, groupID) {
+    let lastEpoch = 0;
+    const exportSecret = ()=>registry.readHandle(groupID, async (handle)=>{
+            lastEpoch = Number(handle.epoch);
+            return await mlsExporter(handle.state.keySchedule.exporterSecret, TOPIC_SECRET_LABEL, TOPIC_SECRET_CONTEXT, TOPIC_SECRET_LENGTH, handle.context.cipherSuite);
+        });
+    const epoch = ()=>lastEpoch;
+    const wrap = (bytes)=>registry.readHandle(groupID, async (handle)=>{
+            const { framed } = await mlsEncryptFramed(handle, bytes);
+            return framed;
+        });
+    // In-flight decrypt cache, keyed by the ciphertext bytes.
+    //
+    // group-rpc subscribes TWO broadcast transports to each app-protocol topic —
+    // the anycast `BroadcastClient` and the `busServer` — and the hub mux fans
+    // every inbound frame to BOTH, so each frame's `unwrap` is invoked twice in the
+    // same synchronous burst. MLS application-message decryption is single-use:
+    // `handle.decrypt` consumes a forward-secret ratchet generation, so a second
+    // decrypt of the same ciphertext fails with "Desired gen in the past" and the
+    // frame never reaches the event handler. Caching the in-flight decrypt promise
+    // per ciphertext makes `unwrap` idempotent: the first call advances the ratchet
+    // once and the sibling transport (which calls before the decrypt resolves)
+    // replays the same plaintext without touching the ratchet. The entry is removed
+    // once it settles, so the cache only ever holds the handful of concurrently
+    // in-flight decrypts — no unbounded growth and never an evicted pending entry.
+    // Distinct ciphertexts always miss and decrypt normally, so forward secrecy
+    // across messages is preserved.
+    const unwrapCache = new Map();
+    const unwrap = (bytes)=>{
+        const key = toB64(bytes);
+        const cached = unwrapCache.get(key);
+        if (cached != null) {
+            return cached;
+        }
+        const promise = registry.readHandle(groupID, async (handle)=>{
+            const payload = await mlsDecryptFramed(handle, bytes);
+            return {
+                payload
+            };
+        });
+        // Drop the entry once it settles (success or failure): the sibling transport
+        // has already taken the in-flight promise, and a genuine failure must not be
+        // cached so a later valid frame with the same bytes (e.g. after a resync) can
+        // decrypt afresh.
+        unwrapCache.set(key, promise);
+        void promise.finally(()=>{
+            unwrapCache.delete(key);
+        });
+        return promise;
+    };
+    return {
+        epoch,
+        exportSecret,
+        wrap,
+        unwrap
+    };
+}

package/lib/groups/group-handle-registry.d.ts

@@ -1,6 +1,6 @@
-import type { GroupHandle } from '@enkaku/group';
 import type { StoreProvider } from '@kubun/db';
 import { type Logger } from '@kubun/logger';
+import type { GroupHandle } from '@kumiai/mls';
 export type GroupHandleRegistryParams = {
     stores: StoreProvider;
     deviceID: string;
@@ -43,6 +43,17 @@ export declare class GroupHandleRegistry {
      * 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
@@ -52,10 +63,23 @@ export declare class GroupHandleRegistry {
     withHandle<T>(groupID: string, fn: (handle: GroupHandle) => Promise<T>, options?: {
         stores?: StoreProvider;
     }): Promise<T>;
+    /**
+     * 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<T>(groupID: string, fn: (handle: GroupHandle) => Promise<T> | T, options?: {
+        stores?: StoreProvider;
+    }): Promise<T>;
     /**
      * Like `withHandle`, but the callback returns `{ result, updated }`.
      * Registry replaces its cached handle with `updated` before persisting on
-     * success. Required for `@enkaku/group` epoch ops (`commitInvite`,
+     * success. Required for `@kumiai/mls` epoch ops (`commitInvite`,
      * `removeMember`, `processCommit`) which construct a fresh `GroupHandle`
      * rather than mutating the input.
      *
@@ -67,6 +91,41 @@ export declare class GroupHandleRegistry {
     }>, options?: {
         stores?: StoreProvider;
     }): Promise<T>;
+    /**
+     * 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.
+     */
+    withHandleReplacingInTransaction<T>(groupID: string, stores: StoreProvider, fn: (handle: GroupHandle, tx: StoreProvider) => Promise<{
+        result: T;
+        updated: GroupHandle;
+    }>): Promise<T>;
     /**
      * 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.