@kubun/store-p2p 0.17.0 → 0.18.0

package/lib/ops/groups.d.ts

@@ -1,12 +1,26 @@
-import type { Adapter } from '@kubun/db-adapter';
+import { type Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
 import type { Group, GroupMember, GroupStatus, InsertGroup, InsertGroupMember, P2PStoreTables, PaginatedResult, PaginationParams } from '../tables.js';
+import { type ClearAppOutboxRowsOptions } from './app-outbox.js';
+export type GetMemberRemovalsParams = {
+    groupIDs: Array<string>;
+    memberDID: string;
+};
 /** Groups and their membership rows. */
 export type GroupOps = {
     createGroup(group: InsertGroup): Promise<void>;
     getGroup(id: string): Promise<Group | undefined>;
     updateGroup(id: string, update: Partial<Pick<InsertGroup, 'name' | 'description' | 'hlc'>>): Promise<void>;
     deleteGroup(id: string): Promise<void>;
+    /** Record that the control projections lag a handle advance named by `token`. */
+    markGroupProjectionsDirty(id: string, token: string): Promise<void>;
+    /**
+     * Clear the dirty mark only if it still holds `token` (`null` matches a clean
+     * group), so an advance that landed meanwhile keeps the group dirty, and
+     * record the handle epoch the projections now reflect. Reports whether the mark
+     * matched.
+     */
+    clearGroupProjectionsDirty(id: string, token: string | null, epoch: number): Promise<boolean>;
     /**
      * The groups this device belongs to. A group it has LEFT is excluded — this
      * is the read every listing is built on, and the default has to be the safe
@@ -14,56 +28,90 @@ export type GroupOps = {
      * not. Use {@link GroupOps.listAllGroups} where a departed group matters.
      */
     listGroups(): Promise<Array<Group>>;
+    /** Pending self-removal groups retained for restart recovery. */
+    listLeavingGroups(): Promise<Array<Group>>;
     /** Every group row, departed ones included. */
     listAllGroups(): Promise<Array<Group>>;
     /**
-     * Move a group between joined and left. Leaving keeps every row hanging off
-     * the group, so being invited back rejoins the SAME group rather than forking
-     * a second row for it.
+     * Move a group between joined and left, retaining membership history for rejoin.
+     * Returns the outbox sequences durably cleared on leave.
      */
-    setGroupStatus(id: string, status: GroupStatus): Promise<void>;
+    /**
+     * Setting left clears the encrypted outbox and pending admission markers.
+     * `requireRevocationsDelivered` refuses leaving or left, writing nothing,
+     * while revocations remain undelivered.
+     */
+    setGroupStatus(id: string, status: GroupStatus, options?: ClearAppOutboxRowsOptions): Promise<Array<number>>;
     listGroupsOffsetPaged(params: PaginationParams): Promise<PaginatedResult<Group>>;
-    addGroupMember(member: InsertGroupMember): Promise<void>;
+    /** Reports whether the invite inserted or updated its target row. */
+    addGroupMember(member: InsertGroupMember): Promise<boolean>;
     /**
      * Add (or revive) several members in a single multi-row insert. Same
      * re-add-clears-tombstone semantics as {@link addGroupMember}, applied to every
      * row. A single statement keeps the whole batch atomic and avoids issuing one
      * round-trip per member on a single-connection adapter. A no-op for an empty list.
+     * Returns the normalized DIDs whose rows were inserted or updated.
      */
-    addGroupMembers(members: Array<InsertGroupMember>): Promise<void>;
+    addGroupMembers(members: Array<InsertGroupMember>): Promise<Set<string>>;
     /**
-     * Soft-delete a member by tombstoning the row with `hlc`. Delegates to
-     * `markMemberRemoved`: earliest-wins LWW, ignore-if-absent. The row stays in
-     * the table (read queries exclude it) so the apply-time check can compare a
-     * mutation's HLC against the removal HLC.
+     * Tombstone the current incarnation and report whether its row matched.
      */
-    removeGroupMember(groupID: string, memberDID: string, hlc: string): Promise<void>;
+    removeGroupMember(groupID: string, memberDID: string, hlc: string): Promise<boolean>;
     /**
-     * Tombstone an existing membership row at `hlc` using earliest-wins LWW: the
-     * removal sticks only when no removal is recorded yet, or when `hlc` precedes
-     * the stored removal HLC. A removal for a `(groupID, memberDID)` with no local
-     * row is a no-op — absence means there is no member to tombstone, and no row
-     * is created.
+     * Tombstone an active row only when its incarnation HLC precedes `hlc`.
+     * An absent row or an existing tombstone is unchanged.
+     * Reports whether the active row matched.
      */
-    markMemberRemoved(groupID: string, memberDID: string, hlc: string): Promise<void>;
+    markMemberRemoved(groupID: string, memberDID: string, hlc: string): Promise<boolean>;
     /**
      * Tombstone several members of one group at `hlc` in a single statement, with
-     * the same earliest-wins LWW and ignore-if-absent semantics as
+     * the same incarnation guard and ignore-if-absent semantics as
      * {@link markMemberRemoved} applied per row. One statement instead of one per
      * member, and the whole batch lands or none of it does. A no-op for an empty
      * list.
+     * Returns the normalized DIDs whose active rows matched.
      */
-    markMembersRemoved(groupID: string, memberDIDs: Array<string>, hlc: string): Promise<void>;
+    markMembersRemoved(groupID: string, memberDIDs: Array<string>, hlc: string): Promise<Set<string>>;
+    /** Target incarnation and removal stamps, including tombstoned members. */
+    listGroupMembershipStamps(groupID: string, memberDIDs: Array<string>): Promise<Array<Pick<GroupMember, 'member_did' | 'hlc' | 'removed_at_hlc'>>>;
     /**
      * Read a membership row's removal state, including tombstoned rows. This is
-     * the only query that sees soft-deleted members. Returns `undefined` when no
-     * row exists; `{ removed_at_hlc: null }` for an active member; and
+     * unfiltered by active status. Returns `undefined` when no row exists;
+     * `{ removed_at_hlc: null }` for an active member; and
      * `{ removed_at_hlc: <hlc> }` for a removed one.
      */
     getMemberRemoval(groupID: string, memberDID: string): Promise<{
         removed_at_hlc: string | null;
     } | undefined>;
+    /**
+     * {@link GroupOps.getMemberRemoval} for one member across groups, keyed by
+     * group id. A group with no row for the member is absent from the map.
+     */
+    getMemberRemovals(params: GetMemberRemovalsParams): Promise<Map<string, {
+        removed_at_hlc: string | null;
+    }>>;
     getGroupMember(groupID: string, memberDID: string): Promise<GroupMember | undefined>;
+    /**
+     * The newest leave-request stamp surfaced for `memberDID` in `groupID`, or
+     * `undefined` if none ever was. Kept across a removal and re-add.
+     */
+    getGroupLeaveRequestHLC(groupID: string, memberDID: string): Promise<string | undefined>;
+    /**
+     * Set the (group, member) leave-request stamp to `hlc`, but only if the row
+     * still holds `expected` — `undefined` meaning no row yet. Answers whether it
+     * wrote.
+     *
+     * A compare-and-set, not an ordering: the caller decides that `hlc` is newer
+     * by parsing both stamps, since text ordering is collation-dependent on
+     * Postgres. This only guards against a concurrent apply having moved the row
+     * between the caller's read and this write.
+     */
+    swapGroupLeaveRequestHLC(params: {
+        groupID: string;
+        memberDID: string;
+        expected: string | undefined;
+        hlc: string;
+    }): Promise<boolean>;
     isGroupMember(groupID: string, memberDID: string): Promise<boolean>;
     /**
      * Whether `did` was a member of `groupID` at the given HLC, ignoring role.

package/lib/ops/groups.js

@@ -1,4 +1,6 @@
 import { normalizeDID } from '@kokuin/token';
+import { chunked } from '@kubun/db-adapter';
+import { clearAppOutboxRows, lockAppOutboxForErasure } from './app-outbox.js';
 export function createGroupOps(db, adapter) {
     const ops = {
         async createGroup (group) {
@@ -18,22 +20,89 @@ export function createGroupOps(db, adapter) {
             if (update.name != null) values.name = update.name;
             if (update.description != null) values.description = update.description;
             if (update.hlc != null) values.hlc = update.hlc;
+            const changed = Object.entries(values);
             values.updated_at = adapter.encodeTimestamp(new Date());
-            await db.updateTable('kubun_p2p_groups').set(values).where('id', '=', id).execute();
+            let query = db.updateTable('kubun_p2p_groups').set(values).where('id', '=', id);
+            // Rewriting the values a row already holds is not a change: a reproject
+            // that agrees with the stored row leaves it, `updated_at` included, alone.
+            if (changed.length > 0) {
+                query = query.where((eb)=>eb.or(changed.map(([column, value])=>eb(column, '<>', value))));
+            }
+            await query.execute();
+        },
+        async markGroupProjectionsDirty (id, token) {
+            await db.updateTable('kubun_p2p_groups').set({
+                projections_dirty: token
+            }).where('id', '=', id).execute();
+        },
+        async clearGroupProjectionsDirty (id, token, epoch) {
+            const result = await db.updateTable('kubun_p2p_groups').set({
+                projections_dirty: null,
+                projections_epoch: epoch
+            }).where('id', '=', id).where('projections_dirty', token == null ? 'is' : '=', token).executeTakeFirst();
+            return (result.numUpdatedRows ?? 0n) > 0n;
+        },
+        async getGroupLeaveRequestHLC (groupID, memberDID) {
+            const row = await db.selectFrom('kubun_p2p_group_leave_requests').select('hlc').where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).executeTakeFirst();
+            return row?.hlc;
+        },
+        async swapGroupLeaveRequestHLC (params) {
+            const memberDID = normalizeDID(params.memberDID);
+            if (params.expected == null) {
+                const inserted = await db.insertInto('kubun_p2p_group_leave_requests').values({
+                    group_id: params.groupID,
+                    member_did: memberDID,
+                    hlc: params.hlc
+                }).onConflict((oc)=>oc.columns([
+                        'group_id',
+                        'member_did'
+                    ]).doNothing()).executeTakeFirst();
+                return (inserted.numInsertedOrUpdatedRows ?? 0n) > 0n;
+            }
+            const updated = await db.updateTable('kubun_p2p_group_leave_requests').set({
+                hlc: params.hlc
+            }).where('group_id', '=', params.groupID).where('member_did', '=', memberDID).where('hlc', '=', params.expected).executeTakeFirst();
+            return (updated.numUpdatedRows ?? 0n) > 0n;
         },
         async deleteGroup (id) {
-            await db.deleteFrom('kubun_p2p_groups').where('id', '=', id).execute();
+            const remove = async (trx)=>{
+                await clearAppOutboxRows(trx, id);
+                await trx.deleteFrom('kubun_p2p_log_handler_completion').where('group_id', '=', id).execute();
+                await trx.deleteFrom('kubun_p2p_catalog_offers').where('group_id', '=', id).execute();
+                await trx.deleteFrom('kubun_p2p_catalog_routes').where('group_id', '=', id).execute();
+                await trx.deleteFrom('kubun_p2p_groups').where('id', '=', id).execute();
+            };
+            // A caller already inside a provider transaction owns atomicity; opening
+            // a nested one is unsupported.
+            if (db.isTransaction) await remove(db);
+            else await db.transaction().execute(remove);
         },
         async listGroups () {
             return await db.selectFrom('kubun_p2p_groups').selectAll().where('status', '=', 'joined').execute();
         },
+        async listLeavingGroups () {
+            return await db.selectFrom('kubun_p2p_groups').selectAll().where('status', '=', 'leaving').execute();
+        },
         async listAllGroups () {
             return await db.selectFrom('kubun_p2p_groups').selectAll().execute();
         },
-        async setGroupStatus (id, status) {
-            await db.updateTable('kubun_p2p_groups').set({
-                status
-            }).where('id', '=', id).execute();
+        async setGroupStatus (id, status, options) {
+            const update = async (tx)=>{
+                let cleared = [];
+                if (status === 'leaving' && options?.requireRevocationsDelivered === true) {
+                    await lockAppOutboxForErasure(tx, id, options);
+                }
+                if (status === 'left') {
+                    cleared = await clearAppOutboxRows(tx, id, options);
+                    await tx.deleteFrom('kubun_p2p_log_handler_completion').where('group_id', '=', id).execute();
+                }
+                await tx.updateTable('kubun_p2p_groups').set({
+                    status
+                }).where('id', '=', id).execute();
+                return cleared;
+            };
+            if (db.isTransaction) return await update(db);
+            return await db.transaction().execute(update);
         },
         async listGroupsOffsetPaged (params) {
             const { limit, offset } = params;
@@ -58,9 +127,7 @@ export function createGroupOps(db, adapter) {
         },
         // --- Group member operations ---
         async addGroupMember (member) {
-            // Re-adding a previously-removed member clears the tombstone and refreshes
-            // the row's HLC, so a member that left and rejoined is active again.
-            await db.insertInto('kubun_p2p_group_members').values({
+            const row = await db.insertInto('kubun_p2p_group_members').values({
                 group_id: member.group_id,
                 member_did: normalizeDID(member.member_did),
                 role: member.role,
@@ -73,13 +140,20 @@ export function createGroupOps(db, adapter) {
                         hlc: eb.ref('excluded.hlc'),
                         removed_at_hlc: null,
                         updated_at: adapter.encodeTimestamp(new Date())
-                    }))).execute();
+                    })).where((eb)=>eb.or([
+                        eb.and([
+                            eb('kubun_p2p_group_members.removed_at_hlc', 'is', null),
+                            eb('kubun_p2p_group_members.hlc', '<', eb.ref('excluded.hlc'))
+                        ]),
+                        eb('kubun_p2p_group_members.removed_at_hlc', '<', eb.ref('excluded.hlc'))
+                    ]))).returning('member_did').executeTakeFirst();
+            return row != null;
         },
         async addGroupMembers (members) {
             if (members.length === 0) {
-                return;
+                return new Set();
             }
-            await db.insertInto('kubun_p2p_group_members').values(members.map((member)=>({
+            const rows = await db.insertInto('kubun_p2p_group_members').values(members.map((member)=>({
                     group_id: member.group_id,
                     member_did: normalizeDID(member.member_did),
                     role: member.role,
@@ -92,38 +166,39 @@ export function createGroupOps(db, adapter) {
                         hlc: eb.ref('excluded.hlc'),
                         removed_at_hlc: null,
                         updated_at: adapter.encodeTimestamp(new Date())
-                    }))).execute();
+                    })).where((eb)=>eb.or([
+                        eb.and([
+                            eb('kubun_p2p_group_members.removed_at_hlc', 'is', null),
+                            eb('kubun_p2p_group_members.hlc', '<', eb.ref('excluded.hlc'))
+                        ]),
+                        eb('kubun_p2p_group_members.removed_at_hlc', '<', eb.ref('excluded.hlc'))
+                    ]))).returning('member_did').execute();
+            return new Set(rows.map((row)=>row.member_did));
         },
-        // Earliest-wins LWW on `removed_at_hlc`: the update lands only when the row
-        // exists AND it is either not yet tombstoned or the incoming `hlc` precedes
-        // the stored removal HLC. A removal for a `(groupID, memberDID)` with no
-        // local row is ignored — there is no member to tombstone, and creating a
-        // row would leak a phantom member. The string `<` compare mirrors the SQL
-        // LWW used by the delegation-token paths: the serialized HLC form is
-        // lexicographically ordered, so SQL ordering matches HLC ordering.
         async markMemberRemoved (groupID, memberDID, hlc) {
-            await db.updateTable('kubun_p2p_group_members').set({
+            const row = await db.updateTable('kubun_p2p_group_members').set({
                 removed_at_hlc: hlc,
                 updated_at: adapter.encodeTimestamp(new Date())
-            }).where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).where((eb)=>eb.or([
-                    eb('removed_at_hlc', 'is', null),
-                    eb('removed_at_hlc', '>', hlc)
-                ])).execute();
+            }).where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).where('removed_at_hlc', 'is', null).where('hlc', '<', hlc).returning('member_did').executeTakeFirst();
+            return row != null;
         },
-        // Same earliest-wins LWW as `markMemberRemoved`, evaluated per row by the
-        // `WHERE`: an absent member matches nothing, and a row already tombstoned at
-        // an earlier HLC keeps its own removal.
         async markMembersRemoved (groupID, memberDIDs, hlc) {
             if (memberDIDs.length === 0) {
-                return;
+                return new Set();
             }
-            await db.updateTable('kubun_p2p_group_members').set({
+            const rows = await db.updateTable('kubun_p2p_group_members').set({
                 removed_at_hlc: hlc,
                 updated_at: adapter.encodeTimestamp(new Date())
-            }).where('group_id', '=', groupID).where('member_did', 'in', memberDIDs.map(normalizeDID)).where((eb)=>eb.or([
-                    eb('removed_at_hlc', 'is', null),
-                    eb('removed_at_hlc', '>', hlc)
-                ])).execute();
+            }).where('group_id', '=', groupID).where('member_did', 'in', memberDIDs.map(normalizeDID)).where('removed_at_hlc', 'is', null).where('hlc', '<', hlc).returning('member_did').execute();
+            return new Set(rows.map((row)=>row.member_did));
+        },
+        async listGroupMembershipStamps (groupID, memberDIDs) {
+            if (memberDIDs.length === 0) return [];
+            return await db.selectFrom('kubun_p2p_group_members').select([
+                'member_did',
+                'hlc',
+                'removed_at_hlc'
+            ]).where('group_id', '=', groupID).where('member_did', 'in', memberDIDs.map(normalizeDID)).execute();
         },
         async getMemberRemoval (groupID, memberDID) {
             const row = await db.selectFrom('kubun_p2p_group_members').select('removed_at_hlc').where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).executeTakeFirst();
@@ -131,8 +206,25 @@ export function createGroupOps(db, adapter) {
                 removed_at_hlc: row.removed_at_hlc
             };
         },
+        async getMemberRemovals (params) {
+            const result = new Map();
+            const groupIDs = [
+                ...new Set(params.groupIDs)
+            ];
+            const memberDID = normalizeDID(params.memberDID);
+            for (const chunk of chunked(groupIDs)){
+                const rows = await db.selectFrom('kubun_p2p_group_members').select([
+                    'group_id',
+                    'removed_at_hlc'
+                ]).where('group_id', 'in', chunk).where('member_did', '=', memberDID).execute();
+                for (const row of rows)result.set(row.group_id, {
+                    removed_at_hlc: row.removed_at_hlc
+                });
+            }
+            return result;
+        },
         async removeGroupMember (groupID, memberDID, hlc) {
-            await ops.markMemberRemoved(groupID, memberDID, hlc);
+            return await ops.markMemberRemoved(groupID, memberDID, hlc);
         },
         async getGroupMember (groupID, memberDID) {
             return await db.selectFrom('kubun_p2p_group_members').selectAll().where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).where('removed_at_hlc', 'is', null).executeTakeFirst();
@@ -237,6 +329,9 @@ export function createGroupOps(db, adapter) {
                 'kubun_p2p_groups.description as description',
                 'kubun_p2p_groups.created_by as created_by',
                 'kubun_p2p_groups.status as status',
+                'kubun_p2p_groups.kind as kind',
+                'kubun_p2p_groups.projections_dirty as projections_dirty',
+                'kubun_p2p_groups.projections_epoch as projections_epoch',
                 'kubun_p2p_groups.hlc as hlc',
                 'kubun_p2p_groups.created_at as created_at',
                 'kubun_p2p_groups.updated_at as updated_at'

package/lib/ops/hubs.js

@@ -1,4 +1,5 @@
 import { sql } from 'kysely';
+import { canonicalHubURL } from '../hub-url.js';
 import { COMMIT_HUB_UNIQUE_INDEX } from '../migrations.js';
 /**
  * Run `write` as a single atomic unit. The store API is built on whatever Kysely
@@ -83,7 +84,7 @@ export function createHubOps(db, adapter) {
             await db.insertInto('kubun_p2p_hubs').values({
                 id: hub.id,
                 label: hub.label,
-                url: hub.url,
+                url: canonicalHubURL(hub.url),
                 server_did: hub.server_did
             }).execute();
         },
@@ -91,12 +92,12 @@ export function createHubOps(db, adapter) {
             return await db.selectFrom('kubun_p2p_hubs').selectAll().where('id', '=', id).executeTakeFirst();
         },
         async getHubByURL (url) {
-            return await db.selectFrom('kubun_p2p_hubs').selectAll().where('url', '=', url).executeTakeFirst();
+            return await db.selectFrom('kubun_p2p_hubs').selectAll().where('url', '=', canonicalHubURL(url)).executeTakeFirst();
         },
         async updateHub (id, update) {
             const values = {};
             if (update.label !== undefined) values.label = update.label;
-            if (update.url !== undefined) values.url = update.url;
+            if (update.url !== undefined) values.url = canonicalHubURL(update.url);
             if (update.server_did !== undefined) values.server_did = update.server_did;
             values.updated_at = adapter.encodeTimestamp(new Date());
             await db.updateTable('kubun_p2p_hubs').set(values).where('id', '=', id).execute();
@@ -148,6 +149,9 @@ export function createHubOps(db, adapter) {
                 'kubun_p2p_groups.description as description',
                 'kubun_p2p_groups.created_by as created_by',
                 'kubun_p2p_groups.status as status',
+                'kubun_p2p_groups.kind as kind',
+                'kubun_p2p_groups.projections_dirty as projections_dirty',
+                'kubun_p2p_groups.projections_epoch as projections_epoch',
                 'kubun_p2p_groups.hlc as hlc',
                 'kubun_p2p_groups.created_at as created_at',
                 'kubun_p2p_groups.updated_at as updated_at'
@@ -195,7 +199,7 @@ export function createHubOps(db, adapter) {
                 // both sides carry a server DID it must match too: the same URL served
                 // by a different server DID is a different hub identity, and flagging it
                 // would designate a peer the group never chose.
-                let matchQuery = tx.selectFrom('kubun_p2p_group_hubs').innerJoin('kubun_p2p_hubs', 'kubun_p2p_hubs.id', 'kubun_p2p_group_hubs.hub_id').select('kubun_p2p_group_hubs.hub_id as hub_id').where('kubun_p2p_group_hubs.group_id', '=', groupID).where('kubun_p2p_hubs.url', '=', commitHub.url);
+                let matchQuery = tx.selectFrom('kubun_p2p_group_hubs').innerJoin('kubun_p2p_hubs', 'kubun_p2p_hubs.id', 'kubun_p2p_group_hubs.hub_id').select('kubun_p2p_group_hubs.hub_id as hub_id').where('kubun_p2p_group_hubs.group_id', '=', groupID).where('kubun_p2p_hubs.url', '=', canonicalHubURL(commitHub.url));
                 if (commitHub.serverDID != null) {
                     // A bound row with no recorded server DID stays eligible — it has not
                     // claimed a conflicting identity, only an unknown one.

package/lib/ops/log-handler-completion.d.ts

@@ -0,0 +1,20 @@
+import type { Kysely } from 'kysely';
+import type { P2PStoreTables } from '../tables.js';
+export type LogHandlerCompletionKey = {
+    groupID: string;
+    procedure: string;
+    /** Verified issuer plus token identity, or the MLS-authenticated announcer. */
+    entity: string;
+    hlc: string;
+};
+export type LogHandlerCompletionOps = {
+    /** Retain the first attempt's notification decision before writing handler state. */
+    beginLogHandlerCompletion(params: BeginLogHandlerCompletionParams): Promise<boolean>;
+    hasLogHandlerCompleted(key: LogHandlerCompletionKey): Promise<boolean>;
+    markLogHandlerCompleted(key: LogHandlerCompletionKey): Promise<void>;
+};
+export type BeginLogHandlerCompletionParams = {
+    key: LogHandlerCompletionKey;
+    notify: boolean;
+};
+export declare function createLogHandlerCompletionOps(db: Kysely<P2PStoreTables>): LogHandlerCompletionOps;

package/lib/ops/log-handler-completion.js

@@ -0,0 +1,41 @@
+export function createLogHandlerCompletionOps(db) {
+    return {
+        async beginLogHandlerCompletion ({ key, notify }) {
+            const row = await db.insertInto('kubun_p2p_log_handler_completion').values({
+                group_id: key.groupID,
+                procedure: key.procedure,
+                entity: key.entity,
+                hlc: key.hlc,
+                notify: notify ? 1 : 0
+            }).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'procedure',
+                    'entity',
+                    'hlc'
+                ]).doUpdateSet({
+                    hlc: key.hlc
+                })).returning('notify').executeTakeFirstOrThrow();
+            return row.notify === 1;
+        },
+        async hasLogHandlerCompleted (key) {
+            const row = await db.selectFrom('kubun_p2p_log_handler_completion').select('hlc').where('group_id', '=', key.groupID).where('procedure', '=', key.procedure).where('entity', '=', key.entity).where('hlc', '=', key.hlc).where('completed', '=', 1).executeTakeFirst();
+            return row != null;
+        },
+        async markLogHandlerCompleted (key) {
+            await db.insertInto('kubun_p2p_log_handler_completion').values({
+                group_id: key.groupID,
+                procedure: key.procedure,
+                entity: key.entity,
+                hlc: key.hlc,
+                completed: 1
+            }).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'procedure',
+                    'entity',
+                    'hlc'
+                ]).doUpdateSet({
+                    completed: 1
+                })).execute();
+        }
+    };
+}

package/lib/ops/mls.d.ts

@@ -1,19 +1,52 @@
 import type { Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
 import type { GroupMLSState, InsertGroupMLSState, P2PStoreTables } from '../tables.js';
+export type ReserveSenderGenerationsParams = {
+    groupID: string;
+    deviceID: string;
+    epoch: number;
+    /** The sender generation encryption has reached. */
+    current: number;
+    /** How many generations past `current` to reserve. */
+    size: number;
+    /** The high-water mark the caller last saw; a different stored mark returns `null`. */
+    expectedHWM: number;
+    /**
+     * The caller's state, stored in place when the row is still at `stateVersion` and the
+     * reservation made here is still the latest. Its sender generation must not exceed
+     * `current`, so it never leads the hwm restore fast-forwards to. The version does not
+     * move, so no other holder of the row loses its CAS; restore then fast-forwards at most
+     * one lease instead of every lease since the last save.
+     */
+    senderState?: {
+        mlsState: Uint8Array;
+        stateVersion: number;
+    };
+};
 /** Per-device MLS state for each group. */
 export type MLSOps = {
-    saveMLSState(state: InsertGroupMLSState): Promise<void>;
-    getMLSState(groupID: string, deviceID: string): Promise<GroupMLSState | undefined>;
-    deleteMLSState(groupID: string, deviceID: string): Promise<void>;
+    /** True when this version was stored; false when a newer state already won. */
+    saveMLSState(state: InsertGroupMLSState, expected?: {
+        epoch: number;
+        stateVersion: number;
+    } | null): Promise<boolean>;
+    /** Atomically reserve sender generations before encryption can use them. */
+    reserveSenderGenerations(params: ReserveSenderGenerationsParams): Promise<number | null>;
+    getMLSState(groupID: string, deviceID: string, options?: {
+        includeDeleted?: boolean;
+    }): Promise<GroupMLSState | undefined>;
+    deleteMLSState(groupID: string, deviceID: string, expected?: {
+        epoch: number;
+        stateVersion: number;
+    }): Promise<boolean>;
     listMLSStates(groupID: string): Promise<Array<GroupMLSState>>;
     /**
      * The groups this device holds MLS state for, keyed on the same `(group_id,
      * device_id)` pair {@link getMLSState} reads.
      *
-     * **No production caller — a test observer.** It once answered "have I joined
-     * this group", which it cannot: a removed device still holds state. Kept for
-     * asserting that a departure left nothing behind.
+     * It does not answer "have I joined this group": a removed device still holds
+     * state. Binding evidence backfill wants exactly that held state, joined or not;
+     * tests use it to assert that a departure left nothing behind.
      */
     listMLSStateGroupIDs(deviceID: string): Promise<Array<string>>;
     deleteGroupMLSStates(groupID: string): Promise<void>;