@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/circle-reducers.js

@@ -0,0 +1,128 @@
+import { normalizeDID } from '@kokuin/token';
+import { foldAdminRoster } from './admin-roster.js';
+/**
+ * Drop the entries whose issuer lacked admin authority at their own slot, keeping
+ * the rest in ledger order.
+ *
+ * INCLUSIVE compare against the ledger prefix through the entry's own position: a
+ * grant authorizes from its own slot onward, a demotion stops authorizing from its
+ * own slot onward.
+ */ export function authorizedEntries(entries, isAdmin) {
+    return entries.filter(({ verified, position })=>isAdmin(verified.issuer, position));
+}
+/**
+ * Ledger entry `type` for a circle-membership claim. Every control-ledger type
+ * kubun mints lives under `kubun.*` — that namespace is kubun's, and the split
+ * between "kubun projects this" and "the MLS library interprets this" is drawn
+ * on it. Namespaces the library reserves for itself are its own to name and
+ * rename, so kubun stays out of them and never restates them.
+ */ export const CIRCLE_MEMBER_ENTRY_TYPE = 'kubun.circle.member';
+/**
+ * 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
+    };
+}
+/** Ledger entry `type` for a circle definition (create / update / delete). */ export const CIRCLE_DEF_ENTRY_TYPE = 'kubun.circle.def';
+/**
+ * Ledger entry `type` for a group-settings claim. Namespaced under `kubun.*`
+ * like every kubun control-ledger type — a bare `group.settings` sits in the
+ * namespace the MLS library reserves, so a commit carrying it is refused whole.
+ */ export const GROUP_SETTINGS_ENTRY_TYPE = 'kubun.group.settings';
+/**
+ * Per-field last-writer-wins group settings. The signed entry's `subject` is the
+ * groupID directly, so no decode is needed. Replayed in the ledger's own
+ * enactment order, so for each field the LAST entry that SETS that field wins
+ * naturally.
+ *
+ * Merges PER FIELD rather than replacing the whole value the way `circle.def` /
+ * `circle.member` do, because these fields are touched in isolation: a name-only
+ * update must not clobber a previously-set description. Presence is
+ * `value.field !== undefined`, not `'field' in value`, so an explicit `undefined`
+ * means no change while `''` or an empty list CLEARS the field.
+ *
+ * Unauthorized entries never reach here — see {@link authorizedEntries}.
+ */ export function createGroupSettingsReducer() {
+    return {
+        type: GROUP_SETTINGS_ENTRY_TYPE,
+        seed: ()=>({
+                settings: new Map()
+            }),
+        // Every entry reaching this fold has already passed the admin gate in
+        // `authorizedEntries`, which judges an entry against the ledger prefix
+        // through its own slot. That question needs the entry's POSITION, which this
+        // hook is not given, so the gate cannot live here.
+        verifyAuthority: ()=>true,
+        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;
+            }
+            if (value.openCircleIDs !== undefined) {
+                next.openCircleIDs = value.openCircleIDs;
+            }
+            if (value.commitHub !== undefined) {
+                next.commitHub = value.commitHub;
+            }
+            settings.set(subject, next);
+            return {
+                settings
+            };
+        }
+    };
+}
+/**
+ * Build an {@link IsAdminAtPosition} predicate from the group's admin-role ledger
+ * entries. It re-folds the admin sub-ledger through each queried slot, so the
+ * answer is rotation-aware (was-admin-then, not is-admin-now): a key granted
+ * admin at slot n authorizes entries from slot n onward, and a later demotion
+ * stops authorizing from its own slot onward. The compare is inclusive
+ * (`position <= throughPosition`), which matters only for a role entry judging
+ * itself — a circle entry never shares a slot with the grant that authorizes it.
+ *
+ * Callers select the role entries once (via `selectRoleEntries`) and reuse the
+ * returned predicate across the circle / def / settings folds.
+ *
+ * LEDGER-ADMIN ONLY — it does not check the issuer's MLS membership, so an admin
+ * removed from the MLS group whose admin role was never revoked on the ledger still
+ * has its entries folded in. Closing that needs removal to write a ledger
+ * revocation atomically with the roster delta; out of scope here.
+ */ export function adminAuthorityFromEntries(adminEntries, anchor, groupID) {
+    return (issuer, position)=>foldAdminRoster(adminEntries, anchor, groupID, position).admins.has(normalizeDID(issuer));
+}

package/lib/groups/commit-adoption.d.ts

@@ -0,0 +1,77 @@
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { P2PEventEmitter } from './events.js';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+import type { SerializedMLSGroupState } from './mls-state.js';
+export type SerializeCommitJournalBlobParams = {
+    serializedHandle: SerializedMLSGroupState;
+    invitePayload?: string;
+    requestID?: string;
+};
+export declare function serializeCommitJournalBlob(params: SerializeCommitJournalBlobParams): Uint8Array;
+/**
+ * Read just the control request id a commit journalled, if it carried one.
+ *
+ * A lost commit the host re-drives (a `ledger` whose tokens survive) is settled
+ * under the SAME id it was first enacted for, and that id lives only in the
+ * blob. This exposes it without re-implementing the codec: the deserialize stays
+ * one function, so the blob shape and its `reviver` are read the same way on
+ * every path. An absent id returns `undefined` — never a placeholder, which
+ * would flow as a real request and settle an unrelated row.
+ */
+export declare function readJournalRequestID(blob: Uint8Array): string | undefined;
+export type AdoptCommitJournalBlobDeps = {
+    registry: GroupHandleRegistry;
+    groupID: string;
+    stores: StoreProvider;
+    /**
+     * Announces the settle this adopt performs. Optional — without it the request
+     * still settles durably, only silently, so a caller reading the row back
+     * still sees the outcome.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Adopt a journalled commit now confirmed accepted: restore its post-commit
+ * handle, swap it into the registry (persisting the advance), and settle the
+ * request it enacted with whatever artifact it produced.
+ *
+ * An invite's payload is PERSISTED here, never sent. A Welcome reaches its
+ * invitee out of band, and by the time a replay runs the caller that would have
+ * carried it there is gone — so the only thing this path can do, and the only
+ * thing it needs to do, is put the payload where that caller's app can still
+ * fetch it by request id.
+ *
+ * Idempotent, as the journal contract requires — a crash between recording
+ * acceptance and clearing the slot replays this. Restoring the serialized handle
+ * is a fixed value, `replaceHandle` installs the same advanced state again, and
+ * a repeated settle rewrites the same terminal row.
+ */
+export declare function adoptCommitJournalBlob(blob: Uint8Array, deps: AdoptCommitJournalBlobDeps): Promise<void>;
+export type SettleLostControlRequestDeps = {
+    stores: StoreProvider;
+    /**
+     * Announces the settle. Optional — without it the request still settles
+     * durably, only silently, so a caller reading the row back still sees the
+     * outcome.
+     */
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Settle the control request a lost commit was enacting as `lost`.
+ *
+ * The mirror image of {@link adoptCommitJournalBlob}: it reads the same blob a
+ * pending commit journalled, but a lost commit NEVER landed, so — unlike the
+ * accepted path — nothing here restores or advances the handle. The only thing
+ * recovered is the request the commit was for, so the caller holding its id
+ * learns the action did not happen. For a remove that notice is the admin's
+ * sole signal that an eviction they believe took effect did not.
+ *
+ * A blob with no request id settles NOTHING: an absent id means no request rode
+ * this commit, and settling a placeholder id would flow as a real request and
+ * mark an unrelated row lost. Idempotent like the adopt path — a repeated
+ * settle rewrites the same terminal row.
+ */
+export declare function settleLostControlRequest(blob: Uint8Array, deps: SettleLostControlRequestDeps): Promise<void>;

package/lib/groups/commit-adoption.js

@@ -0,0 +1,108 @@
+import { settleControlRequest } from './control-request.js';
+import { restoreMLSGroupHandle } from './mls-group-handle.js';
+import { replacer, reviver } from './mls-json.js';
+export function serializeCommitJournalBlob(params) {
+    const blob = {
+        serializedHandle: params.serializedHandle,
+        ...params.invitePayload != null ? {
+            invitePayload: params.invitePayload
+        } : {},
+        ...params.requestID != null ? {
+            requestID: params.requestID
+        } : {}
+    };
+    return new TextEncoder().encode(JSON.stringify(blob, replacer));
+}
+function deserializeCommitJournalBlob(blob) {
+    const json = new TextDecoder().decode(blob);
+    return JSON.parse(json, reviver);
+}
+/**
+ * Read just the control request id a commit journalled, if it carried one.
+ *
+ * A lost commit the host re-drives (a `ledger` whose tokens survive) is settled
+ * under the SAME id it was first enacted for, and that id lives only in the
+ * blob. This exposes it without re-implementing the codec: the deserialize stays
+ * one function, so the blob shape and its `reviver` are read the same way on
+ * every path. An absent id returns `undefined` — never a placeholder, which
+ * would flow as a real request and settle an unrelated row.
+ */ export function readJournalRequestID(blob) {
+    return deserializeCommitJournalBlob(blob).requestID;
+}
+/**
+ * Adopt a journalled commit now confirmed accepted: restore its post-commit
+ * handle, swap it into the registry (persisting the advance), and settle the
+ * request it enacted with whatever artifact it produced.
+ *
+ * An invite's payload is PERSISTED here, never sent. A Welcome reaches its
+ * invitee out of band, and by the time a replay runs the caller that would have
+ * carried it there is gone — so the only thing this path can do, and the only
+ * thing it needs to do, is put the payload where that caller's app can still
+ * fetch it by request id.
+ *
+ * Idempotent, as the journal contract requires — a crash between recording
+ * acceptance and clearing the slot replays this. Restoring the serialized handle
+ * is a fixed value, `replaceHandle` installs the same advanced state again, and
+ * a repeated settle rewrites the same terminal row.
+ */ export async function adoptCommitJournalBlob(blob, deps) {
+    const { serializedHandle, invitePayload, requestID } = deserializeCommitJournalBlob(blob);
+    const handle = await restoreMLSGroupHandle({
+        serialized: serializedHandle
+    });
+    await deps.registry.replaceHandle(deps.groupID, handle, {
+        stores: deps.stores
+    });
+    // Settling here is what closes the loop for a request whose process died
+    // between publishing the commit and adopting it: the commit landed, so its
+    // request landed with it, and the app learns the outcome under the id it has
+    // been holding since before the restart. Idempotent like the rest of this
+    // function — a repeated adopt rewrites the same terminal row.
+    if (requestID != null) {
+        await settleControlRequest({
+            stores: deps.stores,
+            requestID,
+            outcome: 'committed',
+            ...invitePayload != null ? {
+                result: invitePayload
+            } : {},
+            ...deps.emitter != null ? {
+                emitter: deps.emitter
+            } : {},
+            ...deps.logger != null ? {
+                logger: deps.logger
+            } : {}
+        });
+    }
+}
+/**
+ * Settle the control request a lost commit was enacting as `lost`.
+ *
+ * The mirror image of {@link adoptCommitJournalBlob}: it reads the same blob a
+ * pending commit journalled, but a lost commit NEVER landed, so — unlike the
+ * accepted path — nothing here restores or advances the handle. The only thing
+ * recovered is the request the commit was for, so the caller holding its id
+ * learns the action did not happen. For a remove that notice is the admin's
+ * sole signal that an eviction they believe took effect did not.
+ *
+ * A blob with no request id settles NOTHING: an absent id means no request rode
+ * this commit, and settling a placeholder id would flow as a real request and
+ * mark an unrelated row lost. Idempotent like the adopt path — a repeated
+ * settle rewrites the same terminal row.
+ */ export async function settleLostControlRequest(blob, deps) {
+    const { requestID } = deserializeCommitJournalBlob(blob);
+    if (requestID == null) {
+        deps.logger?.debug('lost commit carried no control request to settle');
+        return;
+    }
+    await settleControlRequest({
+        stores: deps.stores,
+        requestID,
+        outcome: 'lost',
+        ...deps.emitter != null ? {
+            emitter: deps.emitter
+        } : {},
+        ...deps.logger != null ? {
+            logger: deps.logger
+        } : {}
+    });
+}

package/lib/groups/commit-journal.d.ts

@@ -0,0 +1,14 @@
+import type { StoreProvider } from '@kubun/db';
+import type { CommitJournal } from '@kumiai/rpc';
+/**
+ * The `@kumiai/rpc` `CommitJournal` port for one group, backed by the device's
+ * single-slot commit-journal store. The port carries no group scope — the group
+ * a peer commits to is fixed for its lifetime — so the adapter closes over
+ * `groupID` and threads it into every store call.
+ *
+ * `get` maps the store's raw selectable (snake_case, decoded blobs) to the port's
+ * `JournalEntry`: an absent row is `null`, a null `accepted_as` omits `acceptedAs`
+ * (the outcome is unknown until the hub answers), and `commit`/`journal` are
+ * copied into fresh `Uint8Array`s the port owns.
+ */
+export declare function createCommitJournal(stores: StoreProvider, groupID: string): CommitJournal;

package/lib/groups/commit-journal.js

@@ -0,0 +1,65 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * The `@kumiai/rpc` `CommitJournal` port for one group, backed by the device's
+ * single-slot commit-journal store. The port carries no group scope — the group
+ * a peer commits to is fixed for its lifetime — so the adapter closes over
+ * `groupID` and threads it into every store call.
+ *
+ * `get` maps the store's raw selectable (snake_case, decoded blobs) to the port's
+ * `JournalEntry`: an absent row is `null`, a null `accepted_as` omits `acceptedAs`
+ * (the outcome is unknown until the hub answers), and `commit`/`journal` are
+ * copied into fresh `Uint8Array`s the port owns.
+ */ export function createCommitJournal(stores, groupID) {
+    return {
+        async put (entry) {
+            const store = await getP2PStore(stores);
+            await store.putCommitJournalEntry({
+                groupID,
+                publishID: entry.publishID,
+                expectedHead: entry.expectedHead,
+                epoch: entry.epoch,
+                ...entry.acceptedAs != null ? {
+                    acceptedAs: entry.acceptedAs
+                } : {},
+                commit: entry.commit,
+                bodies: entry.bodies,
+                kind: entry.kind,
+                journal: entry.journal
+            });
+        },
+        async markAccepted (publishID, sequenceID) {
+            const store = await getP2PStore(stores);
+            await store.markCommitJournalAccepted({
+                groupID,
+                publishID,
+                sequenceID
+            });
+        },
+        async get () {
+            const store = await getP2PStore(stores);
+            const row = await store.getCommitJournalEntry(groupID);
+            if (row == null) {
+                return null;
+            }
+            return {
+                publishID: row.publish_id,
+                expectedHead: row.expected_head,
+                epoch: row.epoch,
+                ...row.accepted_as != null ? {
+                    acceptedAs: row.accepted_as
+                } : {},
+                commit: new Uint8Array(row.commit),
+                bodies: row.bodies,
+                kind: row.kind,
+                journal: new Uint8Array(row.journal)
+            };
+        },
+        async clear (publishID) {
+            const store = await getP2PStore(stores);
+            await store.clearCommitJournalEntry({
+                groupID,
+                publishID
+            });
+        }
+    };
+}

package/lib/groups/control-request.d.ts

@@ -0,0 +1,66 @@
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import { type ControlRequest, type ControlRequestOutcome } from '@kubun/store-p2p';
+import type { ControlRequestData } from '../types.js';
+import type { P2PEventEmitter } from './events.js';
+/**
+ * Project a stored control-request row into its API-facing shape. `kind` and
+ * `status` are stored as bare text (no CHECK constraint), so the store types
+ * them as `string`; only this store's own writers ever produce them, and they
+ * write nothing outside the two unions.
+ */
+export declare function toControlRequestData(row: ControlRequest): ControlRequestData;
+export type SettleControlRequestParams = {
+    stores: StoreProvider;
+    requestID: string;
+    outcome: ControlRequestOutcome;
+    error?: string;
+    /**
+     * The artifact this request produced. Written in the same update as the
+     * status and BEFORE the announcement, so a caller woken by the settle always
+     * finds it there.
+     */
+    result?: string;
+    emitter?: P2PEventEmitter;
+    logger?: Logger;
+};
+/**
+ * Record a control request's terminal outcome and announce it.
+ *
+ * The row is RETAINED — a client holding the id must be able to read the
+ * outcome back — so this only moves `status`/`error`/`settledAt`; the row
+ * leaves on ack alone. The announcement carries the row as it was just
+ * written, read back rather than reconstructed, so a subscriber and a later
+ * query never disagree about the outcome.
+ *
+ * Settling an id with no row (already acked, or never enqueued) is a silent
+ * no-op that announces nothing: there is no outcome for anyone to observe.
+ *
+ * Never throws. Callers are the commit lane and the drive-failure path, where
+ * the outcome has already happened — a bookkeeping fault here cannot un-happen
+ * it, and must not turn an accepted commit into a lane error.
+ */
+export declare function settleControlRequest(params: SettleControlRequestParams): Promise<void>;
+export type AwaitControlRequestSettledParams = {
+    stores: StoreProvider;
+    emitter: P2PEventEmitter;
+    requestID: string;
+    /** Rejects once this many milliseconds pass with the request still pending. */
+    timeoutMs: number;
+};
+/**
+ * Resolve when a control request reaches a terminal status.
+ *
+ * Both halves are load-bearing. The subscription alone loses every request that
+ * settles before the caller gets here — the common case for a fast lane — and
+ * the store read alone cannot observe a settle that has not happened yet. The
+ * listener is registered BEFORE the read so there is no window between them
+ * where a settle is neither in the row nor in the stream.
+ *
+ * The timeout is mandatory and REJECTS: callers await this inside a mutation,
+ * where an unbounded wait is a request that never answers. A request with no
+ * row (never enqueued, or already acked) is indistinguishable from one whose
+ * enqueue has not committed yet, so it waits rather than failing fast, and the
+ * timeout is what ends it.
+ */
+export declare function awaitControlRequestSettled(params: AwaitControlRequestSettledParams): Promise<ControlRequestData>;

package/lib/groups/control-request.js

@@ -0,0 +1,101 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * Project a stored control-request row into its API-facing shape. `kind` and
+ * `status` are stored as bare text (no CHECK constraint), so the store types
+ * them as `string`; only this store's own writers ever produce them, and they
+ * write nothing outside the two unions.
+ */ export function toControlRequestData(row) {
+    return {
+        id: row.id,
+        groupID: row.group_id,
+        kind: row.kind,
+        status: row.status,
+        error: row.error,
+        enqueuedAt: row.enqueued_at,
+        settledAt: row.settled_at
+    };
+}
+/**
+ * Record a control request's terminal outcome and announce it.
+ *
+ * The row is RETAINED — a client holding the id must be able to read the
+ * outcome back — so this only moves `status`/`error`/`settledAt`; the row
+ * leaves on ack alone. The announcement carries the row as it was just
+ * written, read back rather than reconstructed, so a subscriber and a later
+ * query never disagree about the outcome.
+ *
+ * Settling an id with no row (already acked, or never enqueued) is a silent
+ * no-op that announces nothing: there is no outcome for anyone to observe.
+ *
+ * Never throws. Callers are the commit lane and the drive-failure path, where
+ * the outcome has already happened — a bookkeeping fault here cannot un-happen
+ * it, and must not turn an accepted commit into a lane error.
+ */ export async function settleControlRequest(params) {
+    try {
+        const store = await getP2PStore(params.stores);
+        await store.settleControlRequest({
+            id: params.requestID,
+            outcome: params.outcome,
+            ...params.error != null ? {
+                error: params.error
+            } : {},
+            ...params.result != null ? {
+                result: params.result
+            } : {},
+            settledAt: new Date().toISOString()
+        });
+        const row = await store.getControlRequest(params.requestID);
+        if (row == null || params.emitter == null) {
+            return;
+        }
+        await params.emitter.emit('controlRequestSettled', toControlRequestData(row));
+    } catch (error) {
+        params.logger?.error('settling a control request failed', {
+            requestID: params.requestID,
+            outcome: params.outcome,
+            error
+        });
+    }
+}
+/**
+ * Resolve when a control request reaches a terminal status.
+ *
+ * Both halves are load-bearing. The subscription alone loses every request that
+ * settles before the caller gets here — the common case for a fast lane — and
+ * the store read alone cannot observe a settle that has not happened yet. The
+ * listener is registered BEFORE the read so there is no window between them
+ * where a settle is neither in the row nor in the stream.
+ *
+ * The timeout is mandatory and REJECTS: callers await this inside a mutation,
+ * where an unbounded wait is a request that never answers. A request with no
+ * row (never enqueued, or already acked) is indistinguishable from one whose
+ * enqueue has not committed yet, so it waits rather than failing fast, and the
+ * timeout is what ends it.
+ */ export async function awaitControlRequestSettled(params) {
+    const { requestID } = params;
+    let unsubscribe;
+    let timer;
+    try {
+        const settled = new Promise((resolve, reject)=>{
+            unsubscribe = params.emitter.on('controlRequestSettled', (data)=>{
+                if (data.id === requestID) {
+                    resolve(data);
+                }
+            });
+            timer = setTimeout(()=>{
+                reject(new Error(`control request ${requestID} did not settle in ${params.timeoutMs}ms`));
+            }, params.timeoutMs);
+        });
+        const store = await getP2PStore(params.stores);
+        const row = await store.getControlRequest(requestID);
+        if (row != null && row.status !== 'pending') {
+            return toControlRequestData(row);
+        }
+        return await settled;
+    } finally{
+        unsubscribe?.();
+        if (timer != null) {
+            clearTimeout(timer);
+        }
+    }
+}

package/lib/groups/events.d.ts

@@ -1,5 +1,5 @@
-import { EventEmitter } from '@enkaku/event';
-import type { CircleData, CircleMemberData, DelegationData, GroupData, GroupHealthData, GroupMemberData, RevokedDelegationData } from '../types.js';
+import { EventEmitter } from '@sozai/event';
+import type { CircleData, CircleMemberData, ControlRequestData, DelegationData, GroupData, GroupHealthData, GroupMemberData, HubServerDIDChangedData, RevokedDelegationData } from '../types.js';
 export type P2PEventMap = {
     groupJoined: GroupData;
     groupLeft: 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
@@ -51,9 +55,22 @@ export type P2PEventMap = {
         hubID: string;
         hubURL: string;
     };
+    /**
+     * The hub at this URL answers under a different DID than the device had
+     * recorded; the new one is adopted and the connection re-dialled with it.
+     */
+    hubServerDIDChanged: HubServerDIDChangedData;
     delegationTokenAdded: DelegationData;
     delegationTokenRevoked: RevokedDelegationData;
     groupHealthChanged: GroupHealthData;
+    /**
+     * A control request reached a terminal status; carries the settled request as
+     * it was written, so a subscriber and a later query agree on the outcome.
+     * Emitted by the commit lane when a commit lands, by the drive path when the
+     * lane refuses one, and by the restart adopt path for a commit whose process
+     * died before it could report.
+     */
+    controlRequestSettled: ControlRequestData;
 };
 export type P2PEventEmitter = EventEmitter<P2PEventMap>;
 export declare function createP2PEventEmitter(): P2PEventEmitter;

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,24 @@
+import type { GroupContextExtension } from '@kumiai/mls';
+import { type GroupAnchor } from '@kumiai/mls';
+/**
+ * The anchor's opaque `app` slot as kubun writes it. `@kumiai/mls` owns the
+ * anchor container (creator DID, version) and never reads this payload.
+ *
+ * `recoverySecret` is 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.
+ */
+export type GroupAnchorApp = {
+    recoverySecret: string;
+};
+/** Build the genesis-anchor extension for a group kubun is creating. */
+export declare function buildKubunGroupAnchorExtension(creatorDID: string, recoverySecret: string): GroupContextExtension;
+/**
+ * Read the recovery seed out of an anchor's `app` slot. Throws when the payload
+ * is missing or malformed: the anchor is written once by kubun and authenticated
+ * by the GroupInfo signature, so an unreadable seed is corruption, not absence,
+ * and a group whose seed cannot be read cannot participate in recovery.
+ */
+export declare function readRecoverySecret(anchor: GroupAnchor): string;

package/lib/groups/group-anchor.js

@@ -0,0 +1,22 @@
+import { buildCurrentGroupAnchorExtension } from '@kumiai/mls';
+/** Build the genesis-anchor extension for a group kubun is creating. */ export function buildKubunGroupAnchorExtension(creatorDID, recoverySecret) {
+    return buildCurrentGroupAnchorExtension(creatorDID, {
+        recoverySecret
+    });
+}
+/**
+ * Read the recovery seed out of an anchor's `app` slot. Throws when the payload
+ * is missing or malformed: the anchor is written once by kubun and authenticated
+ * by the GroupInfo signature, so an unreadable seed is corruption, not absence,
+ * and a group whose seed cannot be read cannot participate in recovery.
+ */ export function readRecoverySecret(anchor) {
+    const app = anchor.app;
+    if (app == null || typeof app !== 'object') {
+        throw new Error('group anchor carries no application payload; cannot derive recovery secret');
+    }
+    const { recoverySecret } = app;
+    if (typeof recoverySecret !== 'string' || recoverySecret.length === 0) {
+        throw new Error('group anchor carries no recovery secret');
+    }
+    return recoverySecret;
+}