@kubun/store-p2p 0.10.1 → 0.12.0

package/lib/ops/circles.js

@@ -0,0 +1,269 @@
+import { normalizeDID } from '@kokuin/token';
+/**
+ * A member may access an active circle by either arm: an active explicit
+ * membership row, OR the circle being open (`open = 1`) with the member holding
+ * an active row in the circle's group. Both arms gate on `removed_at_hlc` — a
+ * tombstoned membership or group membership grants nothing — and `open` is read
+ * at current state, so closing the circle revokes the open arm immediately.
+ *
+ * Every circle reader shares this one predicate: an open circle carries no
+ * membership rows, so a reader resolving access from `kubun_p2p_circle_members`
+ * alone would see an empty set for a member whose access is purely implicit.
+ * Callers must still filter tombstoned circles themselves.
+ */ function circleAccessPredicate(eb, normalizedDID) {
+    return eb.or([
+        eb.exists(eb.selectFrom('kubun_p2p_circle_members').select('kubun_p2p_circle_members.circle_id').whereRef('kubun_p2p_circle_members.circle_id', '=', 'kubun_p2p_circles.id').where('kubun_p2p_circle_members.member_did', '=', normalizedDID).where('kubun_p2p_circle_members.removed_at_hlc', 'is', null)),
+        eb.and([
+            eb('kubun_p2p_circles.open', '=', 1),
+            eb.exists(eb.selectFrom('kubun_p2p_group_members').select('kubun_p2p_group_members.member_did').whereRef('kubun_p2p_group_members.group_id', '=', 'kubun_p2p_circles.group_id').where('kubun_p2p_group_members.member_did', '=', normalizedDID).where('kubun_p2p_group_members.removed_at_hlc', 'is', null))
+        ])
+    ]);
+}
+export function createCircleOps(db, adapter) {
+    return {
+        async createCircle (circle) {
+            await db.insertInto('kubun_p2p_circles').values({
+                id: circle.id,
+                group_id: circle.group_id,
+                name: circle.name,
+                description: circle.description,
+                catalog_ids: adapter.encodeJSON(circle.catalog_ids),
+                hlc: circle.hlc
+            }).execute();
+        },
+        async getCircle (id, options) {
+            let query = db.selectFrom('kubun_p2p_circles').selectAll().where('id', '=', id);
+            if (!options?.includeRemoved) {
+                query = query.where('removed_at_hlc', 'is', null);
+            }
+            return await query.executeTakeFirst();
+        },
+        async getCircles (ids) {
+            const result = new Map();
+            if (ids.length === 0) return result;
+            const rows = await db.selectFrom('kubun_p2p_circles').selectAll().where('id', 'in', ids).execute();
+            for (const row of rows){
+                result.set(row.id, row);
+            }
+            return result;
+        },
+        async updateCircle (id, update) {
+            const values = {};
+            if (update.name != null) values.name = update.name;
+            if (update.description != null) values.description = update.description;
+            if (update.catalog_ids != null) {
+                values.catalog_ids = adapter.encodeJSON(update.catalog_ids);
+            }
+            if (update.hlc != null) {
+                values.hlc = update.hlc;
+                // A create/update that wins the apply-layer HLC check resurrects a
+                // tombstoned circle: clear the removal alongside the HLC refresh.
+                values.removed_at_hlc = null;
+            }
+            values.updated_at = adapter.encodeTimestamp(new Date());
+            await db.updateTable('kubun_p2p_circles').set(values).where('id', '=', id).execute();
+        },
+        async deleteCircle (id) {
+            await db.deleteFrom('kubun_p2p_circles').where('id', '=', id).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 `circleID` with no local row is
+        // ignored — there is no circle to tombstone, and creating a row would leak
+        // a phantom circle.
+        async markCircleRemoved (circleID, hlc) {
+            await db.updateTable('kubun_p2p_circles').set({
+                removed_at_hlc: hlc,
+                updated_at: adapter.encodeTimestamp(new Date())
+            }).where('id', '=', circleID).where((eb)=>eb.or([
+                    eb('removed_at_hlc', 'is', null),
+                    eb('removed_at_hlc', '>', hlc)
+                ])).execute();
+        },
+        async listCirclesByGroup (groupID, options) {
+            let query = db.selectFrom('kubun_p2p_circles').selectAll().where('group_id', '=', groupID);
+            if (!options?.includeRemoved) {
+                query = query.where('removed_at_hlc', 'is', null);
+            }
+            return await query.execute();
+        },
+        async addCircleMember (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_circle_members').values({
+                circle_id: member.circle_id,
+                member_did: normalizeDID(member.member_did),
+                role: member.role,
+                hlc: member.hlc
+            }).onConflict((oc)=>oc.columns([
+                    'circle_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`, mirroring `markMemberRemoved`: 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
+        // `(circleID, memberDID)` with no local row is ignored — no phantom row is
+        // created.
+        async removeCircleMember (circleID, memberDID, hlc) {
+            await db.updateTable('kubun_p2p_circle_members').set({
+                removed_at_hlc: hlc,
+                updated_at: adapter.encodeTimestamp(new Date())
+            }).where('circle_id', '=', circleID).where('member_did', '=', normalizeDID(memberDID)).where((eb)=>eb.or([
+                    eb('removed_at_hlc', 'is', null),
+                    eb('removed_at_hlc', '>', hlc)
+                ])).execute();
+        },
+        async getCircleMember (circleID, memberDID) {
+            return await db.selectFrom('kubun_p2p_circle_members').selectAll().where('circle_id', '=', circleID).where('member_did', '=', normalizeDID(memberDID)).executeTakeFirst();
+        },
+        async listCircleMembers (circleID, options) {
+            let query = db.selectFrom('kubun_p2p_circle_members').selectAll().where('circle_id', '=', circleID);
+            if (!options?.includeRemoved) {
+                query = query.where('removed_at_hlc', 'is', null);
+            }
+            return await query.execute();
+        },
+        // Read-ACL / sync-scope / write-perimeter source: every active circle the
+        // member can reach, explicitly or through the open arm.
+        async getCirclesForMember (memberDID) {
+            const normalized = normalizeDID(memberDID);
+            return await db.selectFrom('kubun_p2p_circles').selectAll('kubun_p2p_circles').where('kubun_p2p_circles.removed_at_hlc', 'is', null).where((eb)=>circleAccessPredicate(eb, normalized)).execute();
+        },
+        // Read-ACL / sync-scope source: does the member reach any of these circles?
+        async isMemberOfAnyCircle (memberDID, circleIDs) {
+            if (circleIDs.length === 0) return false;
+            const normalized = normalizeDID(memberDID);
+            const row = await db.selectFrom('kubun_p2p_circles').select('kubun_p2p_circles.id').where('kubun_p2p_circles.id', 'in', circleIDs).where('kubun_p2p_circles.removed_at_hlc', 'is', null).where((eb)=>circleAccessPredicate(eb, normalized)).limit(1).executeTakeFirst();
+            return row != null;
+        },
+        // Same predicate as `isMemberOfAnyCircle`, projecting the matching rows
+        // instead of collapsing to a single existence answer.
+        async listAccessibleCircles (memberDID, circleIDs) {
+            if (circleIDs.length === 0) return [];
+            const normalized = normalizeDID(memberDID);
+            const rows = await db.selectFrom('kubun_p2p_circles').select([
+                'kubun_p2p_circles.id',
+                'kubun_p2p_circles.group_id'
+            ]).where('kubun_p2p_circles.id', 'in', circleIDs).where('kubun_p2p_circles.removed_at_hlc', 'is', null).where((eb)=>circleAccessPredicate(eb, normalized)).execute();
+            return rows.map((row)=>({
+                    id: row.id,
+                    groupID: row.group_id
+                }));
+        },
+        // Sync-owner expansion: explicit active members always, plus the group's
+        // active members when the circle is open. A closed, tombstoned, or unknown
+        // circle contributes only its explicit members, so the closed-circle owner
+        // set is unchanged.
+        async listCircleOwners (circleID) {
+            // The explicit rows and the circle row are independent, so both go out at
+            // once; only the group read depends on what the circle says.
+            const [explicit, circle] = await Promise.all([
+                db.selectFrom('kubun_p2p_circle_members').select('member_did').where('circle_id', '=', circleID).where('removed_at_hlc', 'is', null).execute(),
+                db.selectFrom('kubun_p2p_circles').select([
+                    'group_id',
+                    'open'
+                ]).where('id', '=', circleID).where('removed_at_hlc', 'is', null).executeTakeFirst()
+            ]);
+            const owners = new Set(explicit.map((row)=>row.member_did));
+            if (circle != null && circle.open === 1) {
+                const groupMembers = await db.selectFrom('kubun_p2p_group_members').select('member_did').where('group_id', '=', circle.group_id).where('removed_at_hlc', 'is', null).execute();
+                for (const row of groupMembers){
+                    owners.add(row.member_did);
+                }
+            }
+            return Array.from(owners);
+        },
+        // Union of `listCircleOwners` over the set, in three queries: the explicit
+        // rows of every circle, the open ones among them, then the members of those
+        // circles' groups. A closed circle still contributes only its explicit
+        // members, since only the open ids feed the group read.
+        async listOwnersForCircles (circleIDs) {
+            if (circleIDs.length === 0) return [];
+            // First two are independent and go out together; the third needs the open
+            // circles' groups, so it waits.
+            const [explicit, openCircles] = await Promise.all([
+                db.selectFrom('kubun_p2p_circle_members').select('member_did').where('circle_id', 'in', circleIDs).where('removed_at_hlc', 'is', null).execute(),
+                db.selectFrom('kubun_p2p_circles').select('group_id').where('id', 'in', circleIDs).where('removed_at_hlc', 'is', null).where('open', '=', 1).execute()
+            ]);
+            const owners = new Set(explicit.map((row)=>row.member_did));
+            const groupIDs = Array.from(new Set(openCircles.map((row)=>row.group_id)));
+            if (groupIDs.length > 0) {
+                const groupMembers = await db.selectFrom('kubun_p2p_group_members').select('member_did').where('group_id', 'in', groupIDs).where('removed_at_hlc', 'is', null).execute();
+                for (const row of groupMembers){
+                    owners.add(row.member_did);
+                }
+            }
+            return Array.from(owners);
+        },
+        // Materialize the group's current open set onto its circle rows: the listed
+        // circles become open, every other circle in the group closed. The caller
+        // derives `openCircleIDs` from the settings fold, so this write is the
+        // current-state projection with no HLC arbitration of its own.
+        async reconcileCircleOpenFlags (groupID, openCircleIDs) {
+            const now = adapter.encodeTimestamp(new Date());
+            if (openCircleIDs.length > 0) {
+                await db.updateTable('kubun_p2p_circles').set({
+                    open: 1,
+                    updated_at: now
+                }).where('group_id', '=', groupID).where('id', 'in', openCircleIDs).execute();
+            }
+            let closeQuery = db.updateTable('kubun_p2p_circles').set({
+                open: 0,
+                updated_at: now
+            }).where('group_id', '=', groupID);
+            if (openCircleIDs.length > 0) {
+                closeQuery = closeQuery.where('id', 'not in', openCircleIDs);
+            }
+            await closeQuery.execute();
+        },
+        // Unconditional fold-authoritative upsert: every projected column is set
+        // from the supplied derived state, including `removed_at_hlc` (a value
+        // tombstones, null marks active). No HLC guard — the reproject already
+        // resolved the winner via the ledger fold, so the store write must not
+        // re-arbitrate.
+        async reconcileCircleProjection (params) {
+            await db.insertInto('kubun_p2p_circles').values({
+                id: params.id,
+                group_id: params.groupID,
+                name: params.name,
+                description: params.description,
+                catalog_ids: adapter.encodeJSON(params.catalogIDs),
+                hlc: params.hlc,
+                removed_at_hlc: params.removedAtHLC,
+                open: params.open ? 1 : 0
+            }).onConflict((oc)=>oc.column('id').doUpdateSet((eb)=>({
+                        group_id: eb.ref('excluded.group_id'),
+                        name: eb.ref('excluded.name'),
+                        description: eb.ref('excluded.description'),
+                        catalog_ids: eb.ref('excluded.catalog_ids'),
+                        hlc: eb.ref('excluded.hlc'),
+                        removed_at_hlc: eb.ref('excluded.removed_at_hlc'),
+                        open: eb.ref('excluded.open'),
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    }))).execute();
+        },
+        async reconcileCircleMemberProjection (params) {
+            await db.insertInto('kubun_p2p_circle_members').values({
+                circle_id: params.circleID,
+                member_did: normalizeDID(params.memberDID),
+                role: params.role,
+                hlc: params.hlc,
+                removed_at_hlc: params.removedAtHLC
+            }).onConflict((oc)=>oc.columns([
+                    'circle_id',
+                    'member_did'
+                ]).doUpdateSet((eb)=>({
+                        role: eb.ref('excluded.role'),
+                        hlc: eb.ref('excluded.hlc'),
+                        removed_at_hlc: eb.ref('excluded.removed_at_hlc'),
+                        updated_at: adapter.encodeTimestamp(new Date())
+                    }))).execute();
+        }
+    };
+}

package/lib/ops/control.d.ts

@@ -0,0 +1,118 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { CommitJournalEntry, ControlRequest, P2PStoreTables } from '../tables.js';
+export type ControlRequestKind = 'ledger' | 'invite' | 'remove';
+/**
+ * How a control request ended. `no_op` is terminal like the rest: the request
+ * asked for a state that already held, so no commit was ever driven — which is
+ * why it is not `committed`, a status that asserts a hub accepted a commit.
+ */
+export type ControlRequestOutcome = 'committed' | 'rejected' | 'lost' | 'no_op';
+export type CommitJournalEntryKind = 'ledger' | 'invite' | 'remove';
+/** The control-request work queue and the single-slot commit journal. */
+export type ControlOps = {
+    /**
+     * Enqueue a `pending` ControlRequest. `id` is the same id the CommitJournal
+     * carries for this attempt. `enqueuedAt` is caller-supplied (the store never
+     * calls `Date.now()`) so enqueue stays deterministic and testable.
+     */
+    enqueueControlRequest(params: {
+        id: string;
+        groupID: string;
+        kind: ControlRequestKind;
+        enqueuedAt: string;
+    }): Promise<void>;
+    /** A single request by id, regardless of status, or `undefined` if absent (already acked or never enqueued). */
+    getControlRequest(id: string): Promise<ControlRequest | undefined>;
+    /**
+     * The live queue: every `pending` row plus every settled row the client has
+     * not acked yet, whatever its outcome, optionally scoped to `groupID`,
+     * ordered by `enqueuedAt`. This is a work queue, not a history; the control
+     * ledger is the history.
+     */
+    getControlRequests(groupID?: string): Promise<Array<ControlRequest>>;
+    /**
+     * Settle a request: update `status`/`error`/`result`/`settledAt` in place and
+     * RETAIN the row, whatever the outcome. Retention is uniform because a client
+     * holding the request's id must be able to read its outcome back — including
+     * a success — and the settled event itself is only a live subscription, so a
+     * client reloading at the moment a request settles would otherwise miss it.
+     * The row leaves only via `ackControlRequest`. Settling an id that no longer
+     * has a row (already acked) is a no-op.
+     *
+     * A settled row is settled. `pending` is the only non-terminal status, so the
+     * accepted transitions are out of `pending` and a re-settle to the SAME
+     * outcome — the latter because adopting a commit journal is contractually
+     * idempotent and re-settles an already-`committed` row with the same payload.
+     * Anything else (a `committed` request reported `rejected` by a later failure
+     * on an unrelated path) is REFUSED silently: every caller is a producer
+     * already handling a failure, so throwing would replace the real error with a
+     * bookkeeping one. Callers needing the outcome read the row back.
+     */
+    settleControlRequest(params: {
+        id: string;
+        outcome: ControlRequestOutcome;
+        /** Absent leaves any stored error untouched — absent is not "clear it". */
+        error?: string;
+        /**
+         * The artifact this request produced, for the kinds that produce one. Set in
+         * the SAME update as the status, so a reader that learns the request settled
+         * can never find the result missing. Absent leaves any stored artifact
+         * untouched: a re-settle carrying no result must not null out the payload an
+         * earlier one stored.
+         */
+        result?: string;
+        settledAt: string;
+    }): Promise<void>;
+    /**
+     * The settled request's artifact, or `null` when it produced none or the row
+     * is gone. Read separately from the row so the result — which can carry
+     * material a settled-request listing has no business handing out — is only
+     * ever fetched by a caller that asks for it by id.
+     */
+    getControlRequestResult(id: string): Promise<string | null>;
+    /**
+     * Acknowledge a settled row, deleting it — the app's way of saying "I have
+     * observed this outcome." Acking a `pending` (or already-absent) row is a
+     * no-op, never an error. The row's `result` goes with it.
+     */
+    ackControlRequest(id: string): Promise<void>;
+    /**
+     * Write the group's slot, REPLACING whatever it held. Single slot per
+     * group: at most one pending commit at a time. `acceptedAs` is absent by
+     * default (a fresh `put` precedes the publish, before any acceptance is
+     * known); pass it only when re-persisting an already-accepted entry.
+     */
+    putCommitJournalEntry(params: {
+        groupID: string;
+        publishID: string;
+        expectedHead: string | null;
+        epoch: number;
+        acceptedAs?: string;
+        commit: Uint8Array;
+        bodies: Array<string>;
+        kind: CommitJournalEntryKind;
+        journal: Uint8Array;
+    }): Promise<void>;
+    /** The group's slot, or `undefined` if empty. */
+    getCommitJournalEntry(groupID: string): Promise<CommitJournalEntry | undefined>;
+    /**
+     * Record that the hub accepted `publishID` as `sequenceID`. A no-op if the
+     * group's slot no longer holds `publishID` — never a write over a
+     * different pending commit.
+     */
+    markCommitJournalAccepted(params: {
+        groupID: string;
+        publishID: string;
+        sequenceID: string;
+    }): Promise<void>;
+    /**
+     * Delete the group's slot ONLY if it holds `publishID`. A mismatched
+     * `publishID` is a no-op.
+     */
+    clearCommitJournalEntry(params: {
+        groupID: string;
+        publishID: string;
+    }): Promise<void>;
+};
+export declare function createControlOps(db: Kysely<P2PStoreTables>, adapter: Adapter): ControlOps;

package/lib/ops/control.js

@@ -0,0 +1,110 @@
+export function createControlOps(db, adapter) {
+    return {
+        async enqueueControlRequest (params) {
+            await db.insertInto('kubun_p2p_control_requests').values({
+                id: params.id,
+                group_id: params.groupID,
+                kind: params.kind,
+                enqueued_at: params.enqueuedAt
+            }).execute();
+        },
+        async getControlRequest (id) {
+            return await db.selectFrom('kubun_p2p_control_requests').selectAll().where('id', '=', id).executeTakeFirst();
+        },
+        // Every row still in the table is either `pending` or a settled row the
+        // client has not acked yet — no status filter is needed beyond the optional
+        // group scope.
+        async getControlRequests (groupID) {
+            // `enqueued_at` is a caller-supplied string, so equal stamps are routine —
+            // two requests enqueued in one transaction share one. The id breaks the tie
+            // so a page is a stable order rather than the storage engine's whim.
+            let query = db.selectFrom('kubun_p2p_control_requests').selectAll().orderBy('enqueued_at').orderBy('id');
+            if (groupID != null) {
+                query = query.where('group_id', '=', groupID);
+            }
+            return await query.execute();
+        },
+        async settleControlRequest (params) {
+            // Every outcome retains the row: a client that holds the request's id must
+            // be able to read the outcome back, and it cannot do that if a success
+            // vanishes underneath it. The row leaves only when the client acks it.
+            // A no-op if the row is already gone (already acked) — the `WHERE id = ?`
+            // simply matches nothing.
+            //
+            // Absent `error`/`result` mean "leave it alone", never "clear it": an
+            // idempotent re-settle carries only the status it already knows, and
+            // nulling the stored artifact would strip a landed invite of its Welcome.
+            const update = {
+                status: params.outcome,
+                settled_at: params.settledAt
+            };
+            if (params.error !== undefined) {
+                update.error = params.error;
+            }
+            if (params.result !== undefined) {
+                update.result = params.result;
+            }
+            await db.updateTable('kubun_p2p_control_requests').set(update)// The terminal-state guard, in the WHERE so it is decided by the same
+            // statement that writes: only a `pending` row, or a re-settle to the
+            // outcome already stored, matches. A different outcome over a terminal
+            // row matches nothing and the settle is silently dropped — the stored
+            // outcome is the true one, and this is reached from error paths where a
+            // throw would mask the failure that got us here.
+            .where('id', '=', params.id).where((eb)=>eb.or([
+                    eb('status', '=', 'pending'),
+                    eb('status', '=', params.outcome)
+                ])).execute();
+        },
+        async getControlRequestResult (id) {
+            const row = await db.selectFrom('kubun_p2p_control_requests').select('result').where('id', '=', id).executeTakeFirst();
+            return row?.result ?? null;
+        },
+        // Only a settled row is deleted; a `pending` row (or an already-absent id)
+        // matches no row and the delete is a silent no-op.
+        async ackControlRequest (id) {
+            await db.deleteFrom('kubun_p2p_control_requests').where('id', '=', id).where('status', '!=', 'pending').execute();
+        },
+        // --- Commit journal operations ---
+        async putCommitJournalEntry (params) {
+            const values = {
+                group_id: params.groupID,
+                publish_id: params.publishID,
+                expected_head: params.expectedHead,
+                epoch: params.epoch,
+                accepted_as: params.acceptedAs ?? null,
+                commit: adapter.encodeBinary(params.commit),
+                bodies: adapter.encodeJSON(params.bodies),
+                kind: params.kind,
+                journal: adapter.encodeBinary(params.journal)
+            };
+            await db.insertInto('kubun_p2p_commit_journal').values(values)// Single slot per group: a fresh `put` REPLACES the whole row,
+            // whatever it held (including a stale `accepted_as` from a prior
+            // commit's acceptance) — never a merge.
+            .onConflict((oc)=>oc.column('group_id').doUpdateSet((eb)=>({
+                        publish_id: eb.ref('excluded.publish_id'),
+                        expected_head: eb.ref('excluded.expected_head'),
+                        epoch: eb.ref('excluded.epoch'),
+                        accepted_as: eb.ref('excluded.accepted_as'),
+                        commit: eb.ref('excluded.commit'),
+                        bodies: eb.ref('excluded.bodies'),
+                        kind: eb.ref('excluded.kind'),
+                        journal: eb.ref('excluded.journal')
+                    }))).execute();
+        },
+        async getCommitJournalEntry (groupID) {
+            return await db.selectFrom('kubun_p2p_commit_journal').selectAll().where('group_id', '=', groupID).executeTakeFirst();
+        },
+        // A no-op if the slot no longer holds `publishID` (already cleared, or
+        // replaced by a later `put`) — the `WHERE` simply matches no row.
+        async markCommitJournalAccepted (params) {
+            await db.updateTable('kubun_p2p_commit_journal').set({
+                accepted_as: params.sequenceID
+            }).where('group_id', '=', params.groupID).where('publish_id', '=', params.publishID).execute();
+        },
+        // A no-op if the slot no longer holds `publishID` — never deletes a
+        // different pending commit.
+        async clearCommitJournalEntry (params) {
+            await db.deleteFrom('kubun_p2p_commit_journal').where('group_id', '=', params.groupID).where('publish_id', '=', params.publishID).execute();
+        }
+    };
+}

package/lib/ops/delegations.d.ts

@@ -0,0 +1,25 @@
+import type { Kysely } from 'kysely';
+import type { InsertGroupDelegation, P2PStoreTables } from '../tables.js';
+/** The `jti` -> group edges the p2p layer keeps for delegation tokens. */
+export type DelegationOps = {
+    /**
+     * Record the group a delegation `jti` was granted in. Idempotent on `jti`
+     * (the primary key): a re-record for a `jti` already present is a no-op. The
+     * delegation token itself lives in the core delegation store; this edge only
+     * carries the group association the p2p layer needs.
+     */
+    addGroupDelegation(edge: InsertGroupDelegation): Promise<void>;
+    /**
+     * Resolve the group a delegation `jti` was granted in, or `null` when no edge
+     * exists. Used to target revoke broadcasts and to enrich revocation listings
+     * with their originating group.
+     */
+    getGroupIDByJTI(jti: string): Promise<string | null>;
+    /**
+     * Batch variant of {@link getGroupIDByJTI}: resolve the group each `jti` was
+     * granted in, returning a `Map` keyed by `jti`. A `jti` with no edge is absent
+     * from the map. Used to enrich revocation listings without an N+1 lookup.
+     */
+    getGroupIDsByJTIs(jtis: Array<string>): Promise<Map<string, string>>;
+};
+export declare function createDelegationOps(db: Kysely<P2PStoreTables>): DelegationOps;

package/lib/ops/delegations.js

@@ -0,0 +1,27 @@
+export function createDelegationOps(db) {
+    return {
+        async addGroupDelegation (edge) {
+            await db.insertInto('kubun_p2p_group_delegation').values({
+                group_id: edge.group_id,
+                jti: edge.jti
+            }).onConflict((oc)=>oc.column('jti').doNothing()).execute();
+        },
+        async getGroupIDByJTI (jti) {
+            const row = await db.selectFrom('kubun_p2p_group_delegation').select('group_id').where('jti', '=', jti).executeTakeFirst();
+            return row?.group_id ?? null;
+        },
+        async getGroupIDsByJTIs (jtis) {
+            if (jtis.length === 0) {
+                return new Map();
+            }
+            const rows = await db.selectFrom('kubun_p2p_group_delegation').select([
+                'jti',
+                'group_id'
+            ]).where('jti', 'in', jtis).execute();
+            return new Map(rows.map((row)=>[
+                    row.jti,
+                    row.group_id
+                ]));
+        }
+    };
+}

package/lib/ops/discovery.d.ts

@@ -0,0 +1,92 @@
+import type { Adapter } from '@kubun/db-adapter';
+import type { Kysely } from 'kysely';
+import type { LocalPeerProfile, P2PStoreTables, PeerAnnouncement, PeerCapabilityRecord, PendingJoinRequestRow } from '../tables.js';
+export type PutPendingJoinRequestParams = {
+    /** The DID that emitted the request, and the only one that can answer it. */
+    did: string;
+    /** The caller-encoded key package bundle. Never inspected here. */
+    payload: string;
+};
+export type UpsertPeerAnnouncementParams = {
+    groupID: string;
+    /**
+     * The MLS-authenticated announcer. The lane's own attribution, never a value
+     * the announce body carried — it carries none.
+     */
+    peerDID: string;
+    label: string;
+    availability: string;
+    capabilities: Array<PeerCapabilityRecord>;
+    /** The announcer's own stamp, kept so a later frame can be compared against it. */
+    hlc: string;
+    /** The group epoch this device held while applying the announcement. */
+    epoch: number;
+};
+export type SetLocalPeerProfileParams = {
+    /** This device's own DID. */
+    peerDID: string;
+    label: string;
+    availability: string;
+    capabilities: Array<PeerCapabilityRecord>;
+};
+/** The peer-discovery projection: what each co-member's device last advertised. */
+export type DiscoveryOps = {
+    /**
+     * Write one (group, peer) row, REPLACING whatever it held. Dumb by design: the
+     * LWW comparison belongs to the apply path, beside the frame's authentication,
+     * exactly as the access-default rules do — a store that silently declined a
+     * write would leave the caller unable to tell "older" from "stored".
+     */
+    upsertPeerAnnouncement(params: UpsertPeerAnnouncementParams): Promise<void>;
+    /** One peer's row in one group, or `undefined` if it has never announced. */
+    getPeerAnnouncement(params: {
+        groupID: string;
+        peerDID: string;
+    }): Promise<PeerAnnouncement | undefined>;
+    /**
+     * Every row of one group, ordered by peer DID. A caller asserting that some
+     * peer is ABSENT must read the whole set: a point lookup answers only about the
+     * DID it was handed, and the row a mis-attributed write leaves behind is under
+     * a different one.
+     */
+    listPeerAnnouncements(groupID: string): Promise<Array<PeerAnnouncement>>;
+    /**
+     * Drop the rows of one or more peers in one group, in a single statement.
+     *
+     * A HARD delete, unlike the membership tombstone it accompanies: a membership
+     * row is kept so an apply can compare a mutation's HLC against the removal,
+     * while an advertisement carries no authority to compare against and only
+     * answers "who can I reach now". Silence is the one thing that never deletes —
+     * a quiet device goes stale in place; a removed one goes away.
+     *
+     * A no-op for an empty list.
+     */
+    deletePeerAnnouncements(params: {
+        groupID: string;
+        peerDIDs: Array<string>;
+    }): Promise<void>;
+    /**
+     * Record what this device is, replacing whatever it said before. Device-wide:
+     * an announce trigger for a group this device has never announced in has no
+     * other source to read.
+     */
+    setLocalPeerProfile(params: SetLocalPeerProfileParams): Promise<void>;
+    /** What this device last declared itself to be, or `undefined` if it never has. */
+    getLocalPeerProfile(peerDID: string): Promise<LocalPeerProfile | undefined>;
+    /**
+     * Hold the private half of a join request until the invite answering it
+     * arrives. Replaces any earlier request under the same DID — the older key
+     * material can no longer be answered, so keeping it would only leave a second
+     * secret at rest.
+     */
+    putPendingJoinRequest(params: PutPendingJoinRequestParams): Promise<void>;
+    /**
+     * The held request for a DID, or `undefined` once consumed, never made, or
+     * older than the exchange window — an expired bundle would build a leaf from
+     * key material the group has had no reason to expect for a week.
+     */
+    getPendingJoinRequest(did: string): Promise<PendingJoinRequestRow | undefined>;
+    /** Drop the held request. Called the moment it is used, not on a timer. */
+    deletePendingJoinRequest(did: string): Promise<void>;
+};
+export declare function createDiscoveryOps(db: Kysely<P2PStoreTables>, adapter: Adapter): DiscoveryOps;