@kubun/store-p2p 0.11.0 → 0.12.0

package/lib/ops/discovery.js

@@ -0,0 +1,90 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * How long a prepared join request stays usable. The exchange it belongs to is a
+ * human round-trip — a payload pasted into a message, answered whenever the other
+ * person gets to it — so the window is days, not minutes. Past it the request is
+ * abandoned, and an abandoned one is private key material sitting at rest with
+ * nothing left to answer it: the row is deleted rather than kept for a reply that
+ * is not coming.
+ */ const PENDING_JOIN_REQUEST_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** The encoded `created_at` a row must be at or after to still be usable. */ function expiredBefore(adapter) {
+    return adapter.encodeTimestamp(new Date(Date.now() - PENDING_JOIN_REQUEST_TTL_MS));
+}
+export function createDiscoveryOps(db, adapter) {
+    return {
+        async upsertPeerAnnouncement (params) {
+            const values = {
+                group_id: params.groupID,
+                // Canonical DID form on every key, as the membership rows use: the row
+                // is deleted by DIDs the MLS roster names, and a key written in one form
+                // and deleted in another would leave an ex-member's route behind.
+                peer_did: normalizeDID(params.peerDID),
+                label: params.label,
+                availability: params.availability,
+                capabilities: adapter.encodeJSON(params.capabilities),
+                hlc: params.hlc,
+                announced_at: adapter.encodeTimestamp(new Date()),
+                announced_epoch: params.epoch
+            };
+            await db.insertInto('kubun_p2p_peer_announcements').values(values).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'peer_did'
+                ]).doUpdateSet((eb)=>({
+                        label: eb.ref('excluded.label'),
+                        availability: eb.ref('excluded.availability'),
+                        capabilities: eb.ref('excluded.capabilities'),
+                        hlc: eb.ref('excluded.hlc'),
+                        announced_at: eb.ref('excluded.announced_at'),
+                        announced_epoch: eb.ref('excluded.announced_epoch')
+                    }))).execute();
+        },
+        async getPeerAnnouncement (params) {
+            return await db.selectFrom('kubun_p2p_peer_announcements').selectAll().where('group_id', '=', params.groupID).where('peer_did', '=', normalizeDID(params.peerDID)).executeTakeFirst();
+        },
+        async listPeerAnnouncements (groupID) {
+            return await db.selectFrom('kubun_p2p_peer_announcements').selectAll().where('group_id', '=', groupID).orderBy('peer_did').execute();
+        },
+        async deletePeerAnnouncements (params) {
+            if (params.peerDIDs.length === 0) {
+                return;
+            }
+            await db.deleteFrom('kubun_p2p_peer_announcements').where('group_id', '=', params.groupID).where('peer_did', 'in', params.peerDIDs.map(normalizeDID)).execute();
+        },
+        async setLocalPeerProfile (params) {
+            const values = {
+                peer_did: normalizeDID(params.peerDID),
+                label: params.label,
+                availability: params.availability,
+                capabilities: adapter.encodeJSON(params.capabilities),
+                updated_at: adapter.encodeTimestamp(new Date())
+            };
+            await db.insertInto('kubun_p2p_local_peer_profile').values(values).onConflict((oc)=>oc.column('peer_did').doUpdateSet((eb)=>({
+                        label: eb.ref('excluded.label'),
+                        availability: eb.ref('excluded.availability'),
+                        capabilities: eb.ref('excluded.capabilities'),
+                        updated_at: eb.ref('excluded.updated_at')
+                    }))).execute();
+        },
+        async getLocalPeerProfile (peerDID) {
+            return await db.selectFrom('kubun_p2p_local_peer_profile').selectAll().where('peer_did', '=', normalizeDID(peerDID)).executeTakeFirst();
+        },
+        async putPendingJoinRequest (params) {
+            // Swept on write rather than on a timer: preparing a request is the only
+            // moment this table grows, so it is the only moment it needs collecting.
+            await db.deleteFrom('kubun_p2p_pending_join_requests').where('created_at', '<', expiredBefore(adapter)).execute();
+            const values = {
+                did: normalizeDID(params.did),
+                payload: params.payload
+            };
+            await db.insertInto('kubun_p2p_pending_join_requests').values(values).onConflict((oc)=>oc.column('did').doUpdateSet((eb)=>({
+                        payload: eb.ref('excluded.payload')
+                    }))).execute();
+        },
+        async getPendingJoinRequest (did) {
+            return await db.selectFrom('kubun_p2p_pending_join_requests').selectAll().where('did', '=', normalizeDID(did)).where('created_at', '>=', expiredBefore(adapter)).executeTakeFirst();
+        },
+        async deletePendingJoinRequest (did) {
+            await db.deleteFrom('kubun_p2p_pending_join_requests').where('did', '=', normalizeDID(did)).execute();
+        }
+    };
+}

package/lib/ops/groups.d.ts

@@ -0,0 +1,132 @@
+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';
+/** 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>;
+    /**
+     * 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
+     * one or each new caller has to remember the filter and one eventually will
+     * not. Use {@link GroupOps.listAllGroups} where a departed group matters.
+     */
+    listGroups(): 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.
+     */
+    setGroupStatus(id: string, status: GroupStatus): Promise<void>;
+    listGroupsOffsetPaged(params: PaginationParams): Promise<PaginatedResult<Group>>;
+    addGroupMember(member: InsertGroupMember): Promise<void>;
+    /**
+     * 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.
+     */
+    addGroupMembers(members: Array<InsertGroupMember>): Promise<void>;
+    /**
+     * 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.
+     */
+    removeGroupMember(groupID: string, memberDID: string, hlc: string): Promise<void>;
+    /**
+     * 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.
+     */
+    markMemberRemoved(groupID: string, memberDID: string, hlc: string): Promise<void>;
+    /**
+     * Tombstone several members of one group at `hlc` in a single statement, with
+     * the same earliest-wins LWW 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.
+     */
+    markMembersRemoved(groupID: string, memberDIDs: Array<string>, hlc: string): Promise<void>;
+    /**
+     * 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
+     * `{ removed_at_hlc: <hlc> }` for a removed one.
+     */
+    getMemberRemoval(groupID: string, memberDID: string): Promise<{
+        removed_at_hlc: string | null;
+    } | undefined>;
+    getGroupMember(groupID: string, memberDID: string): Promise<GroupMember | undefined>;
+    isGroupMember(groupID: string, memberDID: string): Promise<boolean>;
+    /**
+     * Whether `did` was a member of `groupID` at the given HLC, ignoring role.
+     * Mirrors {@link isGroupAdmin}'s removal-boundary semantics without the
+     * `role = 'admin'` filter: with no `atHLC`, tombstoned rows are excluded
+     * (`removed_at_hlc IS NULL`); with `atHLC`, a member removed at HLC `R` still
+     * counts iff `atHLC < R`. Conjoined with ledger admin authority so an
+     * MLS-removed member loses admin regardless of the ledger.
+     */
+    isGroupMemberAtHLC(groupID: string, did: string, atHLC?: string): Promise<boolean>;
+    /**
+     * Whether `did` holds an active `admin` role in `groupID`. With no `atHLC`,
+     * tombstoned rows are ignored (`removed_at_hlc IS NULL`) — the apply-time
+     * admin check. With `atHLC`, an admin removed at HLC `R` still counts iff the
+     * supplied HLC strictly precedes `R` (`atHLC < R`): a write claiming a moment
+     * before the removal is admitted, one at or after it is denied. This mirrors
+     * the membership boundary in `checkMembership` (which denies at
+     * `removed_at_hlc <= mutationHLC`), so the two checks agree on the
+     * remove-boundary instant.
+     */
+    isGroupAdmin(groupID: string, did: string, atHLC?: string): Promise<boolean>;
+    /**
+     * Overlay the role column for an existing member. Update-only: a grant for a
+     * DID with no membership row is a no-op, since membership is MLS-native and a
+     * non-member can hold no role. Never touches `hlc` or `removed_at_hlc`, so it
+     * neither churns membership LWW nor resurrects a tombstone — it is purely the
+     * projection target for the admin-roster fold.
+     */
+    setGroupMemberRole(groupID: string, memberDID: string, role: string): Promise<void>;
+    /**
+     * Overlay the role column for several members of one group, with the same
+     * update-only semantics as {@link setGroupMemberRole} per row. Grouped by role
+     * so the write costs one statement per DISTINCT role rather than one per
+     * member — a roster reconcile typically moves everyone it touches to one or
+     * two roles. A no-op for an empty list.
+     */
+    setGroupMemberRoles(groupID: string, entries: Array<{
+        memberDID: string;
+        role: string;
+    }>): Promise<void>;
+    isMemberOfAnyGroup(viewerDID: string, groupIDs: Array<string>): Promise<boolean>;
+    /**
+     * WHICH of `groupIDs` the member holds an active row in — {@link isGroupMember}
+     * over a set, in one query, for a caller that must know per group rather than
+     * "any".
+     *
+     * Reads the membership rows ONLY. Not interchangeable with
+     * {@link getGroupsForMember}, which inner-joins `kubun_p2p_groups` and so
+     * answers false for a membership whose group row this device does not hold —
+     * an authorization gate must not deny on that.
+     */
+    listMemberGroupIDs(memberDID: string, groupIDs: Array<string>): Promise<Array<string>>;
+    listGroupMembers(groupID: string): Promise<Array<GroupMember>>;
+    getGroupsForMember(memberDID: string): Promise<Array<Group>>;
+    /**
+     * Batch fetch groups for multiple members. Returns a Map keyed by
+     * `memberDID`; values are arrays of groups for that member. Members with
+     * no groups are absent from the map. Single SQL query joining
+     * `group_members` to `groups`. Empty input short-circuits with an empty
+     * Map (no SQL).
+     *
+     * Caller is responsible for deduplicating DIDs.
+     */
+    getGroupsForMembers(memberDIDs: Array<string>): Promise<Map<string, Array<Group>>>;
+};
+export declare function createGroupOps(db: Kysely<P2PStoreTables>, adapter: Adapter): GroupOps;

package/lib/ops/groups.js

@@ -0,0 +1,259 @@
+import { normalizeDID } from '@kokuin/token';
+export function createGroupOps(db, adapter) {
+    const ops = {
+        async createGroup (group) {
+            await db.insertInto('kubun_p2p_groups').values({
+                id: group.id,
+                name: group.name,
+                description: group.description,
+                created_by: group.created_by,
+                hlc: group.hlc
+            }).execute();
+        },
+        async getGroup (id) {
+            return await db.selectFrom('kubun_p2p_groups').selectAll().where('id', '=', id).executeTakeFirst();
+        },
+        async updateGroup (id, update) {
+            const values = {};
+            if (update.name != null) values.name = update.name;
+            if (update.description != null) values.description = update.description;
+            if (update.hlc != null) values.hlc = update.hlc;
+            values.updated_at = adapter.encodeTimestamp(new Date());
+            await db.updateTable('kubun_p2p_groups').set(values).where('id', '=', id).execute();
+        },
+        async deleteGroup (id) {
+            await db.deleteFrom('kubun_p2p_groups').where('id', '=', id).execute();
+        },
+        async listGroups () {
+            return await db.selectFrom('kubun_p2p_groups').selectAll().where('status', '=', 'joined').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 listGroupsOffsetPaged (params) {
+            const { limit, offset } = params;
+            let query = db.selectFrom('kubun_p2p_groups').selectAll().where('status', '=', 'joined').orderBy('name');
+            if (offset != null) {
+                query = query.offset(offset);
+            }
+            if (limit != null) {
+                query = query.limit(limit + 1);
+                const rows = await query.execute();
+                const hasMore = rows.length > limit;
+                return {
+                    entries: hasMore ? rows.slice(0, limit) : rows,
+                    hasMore
+                };
+            }
+            const rows = await query.execute();
+            return {
+                entries: rows,
+                hasMore: false
+            };
+        },
+        // --- 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({
+                group_id: member.group_id,
+                member_did: normalizeDID(member.member_did),
+                role: member.role,
+                hlc: member.hlc
+            }).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'member_did'
+                ]).doUpdateSet((eb)=>({
+                        role: eb.ref('excluded.role'),
+                        hlc: eb.ref('excluded.hlc'),
+                        removed_at_hlc: null,
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    }))).execute();
+        },
+        async addGroupMembers (members) {
+            if (members.length === 0) {
+                return;
+            }
+            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,
+                    hlc: member.hlc
+                }))).onConflict((oc)=>oc.columns([
+                    'group_id',
+                    'member_did'
+                ]).doUpdateSet((eb)=>({
+                        role: eb.ref('excluded.role'),
+                        hlc: eb.ref('excluded.hlc'),
+                        removed_at_hlc: null,
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    }))).execute();
+        },
+        // 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({
+                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();
+        },
+        // 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;
+            }
+            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();
+        },
+        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();
+            return row == null ? undefined : {
+                removed_at_hlc: row.removed_at_hlc
+            };
+        },
+        async removeGroupMember (groupID, memberDID, hlc) {
+            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();
+        },
+        async isGroupMember (groupID, memberDID) {
+            const row = await db.selectFrom('kubun_p2p_group_members').select('member_did').where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).where('removed_at_hlc', 'is', null).executeTakeFirst();
+            return row != null;
+        },
+        async isGroupMemberAtHLC (groupID, did, atHLC) {
+            let query = db.selectFrom('kubun_p2p_group_members').select('member_did').where('group_id', '=', groupID).where('member_did', '=', normalizeDID(did));
+            if (atHLC == null) {
+                query = query.where('removed_at_hlc', 'is', null);
+            } else {
+                query = query.where((eb)=>eb.or([
+                        eb('removed_at_hlc', 'is', null),
+                        eb('removed_at_hlc', '>', atHLC)
+                    ]));
+            }
+            const row = await query.limit(1).executeTakeFirst();
+            return row != null;
+        },
+        async isGroupAdmin (groupID, did, atHLC) {
+            let query = db.selectFrom('kubun_p2p_group_members').select('member_did').where('group_id', '=', groupID).where('member_did', '=', normalizeDID(did)).where('role', '=', 'admin');
+            if (atHLC == null) {
+                query = query.where('removed_at_hlc', 'is', null);
+            } else {
+                // Admit a write whose HLC strictly precedes the removal HLC; deny
+                // at-or-after. Complements `checkMembership`'s `removed_at_hlc <= hlc`
+                // denial so both agree on the remove-boundary instant.
+                query = query.where((eb)=>eb.or([
+                        eb('removed_at_hlc', 'is', null),
+                        eb('removed_at_hlc', '>', atHLC)
+                    ]));
+            }
+            const row = await query.limit(1).executeTakeFirst();
+            return row != null;
+        },
+        async setGroupMemberRole (groupID, memberDID, role) {
+            // Update-only by design: a missing row leaves the table untouched, so a
+            // role grant can never conjure a phantom member. hlc/removed_at_hlc are
+            // left alone to keep membership LWW and tombstones intact.
+            await db.updateTable('kubun_p2p_group_members').set({
+                role,
+                updated_at: adapter.encodeTimestamp(new Date())
+            }).where('group_id', '=', groupID).where('member_did', '=', normalizeDID(memberDID)).execute();
+        },
+        // Grouped by role, then one update per distinct role. Update-only like the
+        // single-member writer, and `hlc`/`removed_at_hlc` are left alone, so a
+        // tombstoned row keeps the role it held when it was removed.
+        async setGroupMemberRoles (groupID, entries) {
+            if (entries.length === 0) {
+                return;
+            }
+            const didsByRole = new Map();
+            for (const entry of entries){
+                const dids = didsByRole.get(entry.role);
+                if (dids == null) {
+                    didsByRole.set(entry.role, [
+                        normalizeDID(entry.memberDID)
+                    ]);
+                } else {
+                    dids.push(normalizeDID(entry.memberDID));
+                }
+            }
+            const now = adapter.encodeTimestamp(new Date());
+            for (const [role, dids] of didsByRole){
+                await db.updateTable('kubun_p2p_group_members').set({
+                    role,
+                    updated_at: now
+                }).where('group_id', '=', groupID).where('member_did', 'in', dids).execute();
+            }
+        },
+        async isMemberOfAnyGroup (viewerDID, groupIDs) {
+            if (groupIDs.length === 0) return false;
+            const row = await db.selectFrom('kubun_p2p_group_members').select('group_id').where('member_did', '=', normalizeDID(viewerDID)).where('group_id', 'in', groupIDs).where('removed_at_hlc', 'is', null).limit(1).executeTakeFirst();
+            return row != null;
+        },
+        // Same predicate as `isGroupMember`, projecting the matching group ids rather
+        // than collapsing to one existence answer. No join to `kubun_p2p_groups` —
+        // membership stands on its own row.
+        async listMemberGroupIDs (memberDID, groupIDs) {
+            if (groupIDs.length === 0) return [];
+            const rows = await db.selectFrom('kubun_p2p_group_members').select('group_id').where('member_did', '=', normalizeDID(memberDID)).where('group_id', 'in', groupIDs).where('removed_at_hlc', 'is', null).execute();
+            return rows.map((row)=>row.group_id);
+        },
+        async listGroupMembers (groupID) {
+            return await db.selectFrom('kubun_p2p_group_members').selectAll().where('group_id', '=', groupID).where('removed_at_hlc', 'is', null).execute();
+        },
+        async getGroupsForMember (memberDID) {
+            return await db.selectFrom('kubun_p2p_group_members').innerJoin('kubun_p2p_groups', 'kubun_p2p_groups.id', 'kubun_p2p_group_members.group_id').selectAll('kubun_p2p_groups').where('kubun_p2p_group_members.member_did', '=', normalizeDID(memberDID)).where('kubun_p2p_group_members.removed_at_hlc', 'is', null).execute();
+        },
+        // Result Map is keyed by the normalized stored `member_did`; callers must
+        // normalize before looking up by key (existing callers iterate `.values()`).
+        async getGroupsForMembers (memberDIDs) {
+            const result = new Map();
+            if (memberDIDs.length === 0) return result;
+            const normalizedDIDs = memberDIDs.map(normalizeDID);
+            const rows = await db.selectFrom('kubun_p2p_group_members').innerJoin('kubun_p2p_groups', 'kubun_p2p_groups.id', 'kubun_p2p_group_members.group_id').select([
+                'kubun_p2p_group_members.member_did as member_did',
+                'kubun_p2p_groups.id as id',
+                'kubun_p2p_groups.name as name',
+                'kubun_p2p_groups.description as description',
+                'kubun_p2p_groups.created_by as created_by',
+                'kubun_p2p_groups.status as status',
+                'kubun_p2p_groups.hlc as hlc',
+                'kubun_p2p_groups.created_at as created_at',
+                'kubun_p2p_groups.updated_at as updated_at'
+            ]).where('kubun_p2p_group_members.member_did', 'in', normalizedDIDs).where('kubun_p2p_group_members.removed_at_hlc', 'is', null).execute();
+            for (const row of rows){
+                const { member_did, ...group } = row;
+                const list = result.get(member_did);
+                if (list != null) {
+                    list.push(group);
+                } else {
+                    result.set(member_did, [
+                        group
+                    ]);
+                }
+            }
+            return result;
+        }
+    };
+    return ops;
+}

package/lib/ops/hubs.d.ts

@@ -0,0 +1,56 @@
+import type { Adapter } from '@kubun/db-adapter';
+import { type Kysely } from 'kysely';
+import type { Group, Hub, InsertGroupHub, InsertHub, P2PStoreTables } from '../tables.js';
+/** Hubs, their group bindings, and the canonical commit-hub designation. */
+export type HubOps = {
+    insertHub(hub: InsertHub): Promise<void>;
+    getHub(id: string): Promise<Hub | undefined>;
+    getHubByURL(url: string): Promise<Hub | undefined>;
+    updateHub(id: string, update: Partial<Pick<InsertHub, 'label' | 'url' | 'server_did'>>): Promise<void>;
+    deleteHub(id: string): Promise<void>;
+    listHubs(): Promise<Array<Hub>>;
+    insertGroupHub(binding: InsertGroupHub): Promise<boolean>;
+    deleteGroupHub(params: {
+        groupID: string;
+        hubID: string;
+    }): Promise<boolean>;
+    listGroupIDsByHubID(hubID: string): Promise<Array<string>>;
+    listHubsByGroupID(groupID: string): Promise<Array<Hub>>;
+    listGroupsByHubID(hubID: string): Promise<Array<Group>>;
+    deleteGroupHubsByHubID(hubID: string): Promise<void>;
+    /** The group's designated commit hub (join to the hub row), or `undefined`. */
+    getCommitHub(groupID: string): Promise<Hub | undefined>;
+    /**
+     * Designate `hubID` as the group's sole commit hub, clearing any prior
+     * designation first so at most one row per group carries the flag. The hub
+     * must already be bound to the group — an unbound `hubID` throws rather than
+     * clearing every flag and setting none.
+     */
+    setCommitHub(params: {
+        groupID: string;
+        hubID: string;
+    }): Promise<void>;
+    /**
+     * Materialize the group's folded commit-hub designation onto the local
+     * `is_commit_hub` flag, so consensus — not each device's first hub-bind —
+     * decides which bound hub the group commits through. `commitHub` is the shared
+     * hub identity (URL, optional server DID), which the caller derives from the
+     * group-settings fold.
+     *
+     * When `commitHub` is given, set `is_commit_hub = 1` on the bound hub whose URL
+     * matches and `0` on every other bound hub of the group. A designation that
+     * carries a server DID additionally requires the bound hub's recorded server
+     * DID to match or to be absent — the same URL under a different server DID is a
+     * different hub identity. When `commitHub` is `undefined`, no-op: the group has folded no designation, so the local
+     * auto-designated flag stands. When the designated URL matches NO bound hub —
+     * the device has not bound the designated hub — clear the flag on every one of
+     * the group's rows: the device has no local commit peer, and keeping a
+     * non-designated hub flagged is exactly the fork this designation prevents. The
+     * device then cannot commit until it binds the designated hub.
+     */
+    reconcileCommitHub(groupID: string, commitHub: {
+        url: string;
+        serverDID?: string;
+    } | undefined): Promise<void>;
+};
+export declare function createHubOps(db: Kysely<P2PStoreTables>, adapter: Adapter): HubOps;