@kubun/plugin-p2p 0.11.0 → 0.12.0

package/lib/types.d.ts

@@ -1,4 +1,8 @@
 import type { ClientTransportOf } from '@enkaku/protocol';
+import type { AccessLevel } from '@kubun/store-graph';
+import type { ControlRequestKind, ControlRequestOutcome } from '@kubun/store-p2p';
+import type { PeerAvailability, PeerCapability } from './groups/group-protocols.js';
+import type { PeerConnection } from './peer/connection-registry.js';
 import type { SyncDirection, SyncProtocol } from './protocol.js';
 import type { PeerConfig, PeerConfigWithID } from './sync/peer-registry.js';
 import type { SyncScope } from './sync/sync-client.js';
@@ -30,8 +34,29 @@ export type CircleData = {
     groupID: string;
     name: string;
     description: string;
+    /** Admin-authored: every group member reaches an open circle implicitly. */
+    open: boolean;
     createdAt: string;
 };
+/** `pending` until the commit lands, then whichever outcome it landed on. */
+export type ControlRequestStatusValue = 'pending' | ControlRequestOutcome;
+/**
+ * One entry of this device's control-request queue. Retained after settling,
+ * whatever the outcome, until the app acks it.
+ *
+ * Every `request*` operation below returns one of these rather than the row it
+ * asks for: a control entry moves a projection only when the commit carrying it is
+ * ENACTED, so at return the requested state is nowhere yet.
+ */
+export type ControlRequestData = {
+    id: string;
+    groupID: string;
+    kind: ControlRequestKind;
+    status: ControlRequestStatusValue;
+    error: string | null;
+    enqueuedAt: string;
+    settledAt: string | null;
+};
 export type CircleMemberData = {
     circleID: string;
     memberDID: string;
@@ -44,6 +69,11 @@ export type CatalogData = {
     name: string;
     description: string;
     filterCriteria: string;
+    /** Local sync activation: true = active, false = known (not activated). */
+    active: boolean;
+    /** First-discovery provenance; null for own catalogs. */
+    sourceGroupID: string | null;
+    sourceCircleID: string | null;
     createdAt: string;
 };
 export type HubData = {
@@ -54,8 +84,34 @@ export type HubData = {
     createdAt: string;
     updatedAt: string | null;
 };
+/**
+ * A hub answered under a DID other than the one this device had recorded, and
+ * the new one has been adopted. A rotated hub key is routine, so the device
+ * reconnects rather than refusing — but it is never silent: the application is
+ * told which hub changed identity, and from what to what.
+ */
+export type HubServerDIDChangedData = {
+    hubURL: string;
+    /** The DID that was recorded before the change — never absent, or there is no change. */
+    previousServerDID: string;
+    /** The DID the hub now advertises at `/info`, now recorded in its place. */
+    serverDID: string;
+};
+export type InviteToGroupInput = {
+    groupID: string;
+    joinRequest: string;
+    grants?: Array<string>;
+    revocations?: Array<string>;
+};
 export type InviteToGroupData = {
-    invitePayload: string;
+    /** The settled request the invite was enacted through. */
+    request: ControlRequestData;
+    /**
+     * Welcome + ratchet tree for the joiner. `null` while the Add commit is parked
+     * (inviter offline) and `request.status` is `pending`. A settled-negative invite
+     * throws rather than returning null here.
+     */
+    invitePayload: string | null;
     groupID: string;
     groupName: string;
 };
@@ -65,16 +121,35 @@ export type JoinGroupData = {
 export type LeaveGroupData = {
     groupID: string;
 };
-export type RemoveGroupMemberData = {
+export type RemoveGroupMemberInput = {
     groupID: string;
+    memberDID: string;
 };
 export type DeleteCatalogData = {
     deletedID: string;
 };
-export type DeleteCircleData = {
-    deletedID: string;
+export type CreateCircleInput = {
+    groupID: string;
+    name: string;
+    description?: string;
+    /**
+     * Internal callers only, never the GraphQL surface, and it MUST be DERIVED:
+     * `circle.def` is whole-value LWW per subject, so two callers naming one id merge
+     * two access scopes — and a member subject embeds the circle id, so both callers'
+     * grants land in the merged scope. A derived id is safe because a collision then
+     * means they meant the same circle. Omitted, one is minted.
+     */
+    circleID?: string;
+};
+export type AddCircleMemberInput = {
+    circleID: string;
+    memberDID: string;
+    role: string;
+};
+export type DeleteCircleInput = {
+    circleID: string;
 };
-export type RemoveCircleMemberData = {
+export type RemoveCircleMemberInput = {
     circleID: string;
     memberDID: string;
 };
@@ -82,6 +157,17 @@ export type UpdateGroupInput = {
     groupID: string;
     name?: string;
     description?: string;
+    /** Circles admins mark open. */
+    openCircleIDs?: Array<string>;
+    /**
+     * The group's commit-hub designation: the shared hub identity every device
+     * folds and commits through. Setting it is admin re-designation; omitting it
+     * leaves the prior designation in place.
+     */
+    commitHub?: {
+        url: string;
+        serverDID?: string | null;
+    };
 };
 export type UpdateCircleInput = {
     circleID: string;
@@ -100,54 +186,154 @@ export type GroupRequestContext = {
     }) => Promise<GroupData>;
     list: () => Promise<Array<GroupData>>;
     get: (id: string) => Promise<GroupData | null>;
-    addMember: (groupID: string, memberDID: string, role: string) => Promise<GroupMemberData>;
     /**
-     * Promote a member to admin or demote them back to member by emitting a
-     * self-signed `group.role.admin` ledger entry. Authority is rooted at the
-     * group's genesis anchor and folded on every peer, so a non-admin caller is
-     * rejected and the change converges identically across the group.
+     * Throw unless the calling identity is an admin of the group, with
+     * `extensions.code = 'KB14'` and `extensions.reason = 'NOT_GROUP_ADMIN'`.
+     *
+     * Exposed so a caller can gate BEFORE entering the transaction wrapper, which
+     * re-raises and strips extensions — that ordering is what keeps the code visible.
      */
-    setMemberRole: (params: {
+    requireAdmin: (groupID: string, action: string) => Promise<void>;
+    /**
+     * `requireAdmin` for an operation that only knows a circle: resolves the
+     * circle's group and gates on that.
+     *
+     * An unknown circle resolves to no group and is NOT refused here, so a missing
+     * circle never reads as an authority problem.
+     */
+    requireCircleAdmin: (circleID: string, action: string) => Promise<void>;
+    /**
+     * Whether `did` is an admin right now, from the same membership row
+     * `requireAdmin` gates on — so a read surface cannot offer a control the gate
+     * refuses.
+     */
+    isAdmin: (groupID: string, did: string) => Promise<boolean>;
+    /**
+     * Promote or demote a member, by emitting a self-signed role ledger entry that
+     * rides an MLS commit. Authority is the member row's mirrored role.
+     *
+     * Demoting a DID that is not currently an admin is minted already settled.
+     */
+    requestSetMemberRole: (params: {
         groupID: string;
         memberDID: string;
         role: 'admin' | 'member';
-    }) => Promise<GroupMemberData>;
+    }) => Promise<ControlRequestData>;
     listMembers: (groupID: string) => Promise<Array<GroupMemberData>>;
-    createCircle: (params: {
-        groupID: string;
-        name: string;
-        description?: string;
-    }) => Promise<CircleData>;
+    /**
+     * Request a new circle, by emitting a self-signed `circle.def` entry that rides
+     * an MLS commit. Authority is the caller's mirrored admin role.
+     *
+     * The id is minted here and handed back immediately, because every step that
+     * follows a create names the circle by id.
+     */
+    requestCreateCircle: (input: CreateCircleInput) => Promise<{
+        request: ControlRequestData;
+        circleID: string;
+    }>;
     listCircles: (groupID: string) => Promise<Array<CircleData>>;
-    addCircleMember: (circleID: string, memberDID: string, role: string) => Promise<CircleMemberData>;
+    /**
+     * Add a DID to a circle at a role, by emitting a self-signed `circle.member`
+     * entry that rides an MLS commit. Re-adding an active member at a DIFFERENT role
+     * is how a role change is expressed; re-adding at the same role settles `no_op`.
+     */
+    requestAddCircleMember: (input: AddCircleMemberInput) => Promise<ControlRequestData>;
     createCatalog: (params: {
         name: string;
         description?: string;
         filterCriteria: string;
+        /**
+         * Internal callers only, and it must be DERIVED so a re-run converges on the
+         * same catalog. Omitted, one is minted.
+         */
+        catalogID?: string;
     }) => Promise<CatalogData>;
-    listCatalogs: (ownerDID?: string) => Promise<Array<CatalogData>>;
+    /** All locally-known catalogs (any owner), optionally filtered by activation. */
+    listStoredCatalogs: (filter?: {
+        active?: boolean;
+    }) => Promise<Array<CatalogData>>;
+    /**
+     * This device's un-acked control requests, oldest first. The store is
+     * per-device, so the queue is viewer-scoped by the database itself.
+     */
+    listControlRequests: (groupID?: string) => Promise<Array<ControlRequestData>>;
+    /** One control request by id, or `null` if it was never enqueued or is already acked. */
+    getControlRequest: (id: string) => Promise<ControlRequestData | null>;
     /**
-     * Build an invite payload for a join request.
+     * Drop a settled request from the queue. Acking a `pending` (or unknown)
+     * request is a no-op, never an error.
+     */
+    ackControlRequest: (id: string) => Promise<void>;
+    /**
+     * Resolve when a control request reaches a terminal status, with the settled
+     * request. For a caller that must not run its next step until this one landed.
+     *
+     * Rejects when `timeoutMs` elapses with the request still pending: callers
+     * await this inside a mutation, where waiting forever is a request that never
+     * answers.
+     */
+    awaitSettle: (id: string, timeoutMs: number) => Promise<ControlRequestData>;
+    /** Turn on local sync for a known catalog. Throws on an unknown catalogID. */
+    activateCatalogSync: (catalogID: string) => Promise<CatalogData>;
+    /** Turn off local sync for a catalog. Throws on an unknown catalogID. */
+    deactivateCatalogSync: (catalogID: string) => Promise<CatalogData>;
+    /**
+     * Request an invite for a join request, by driving an MLS Add commit, and
+     * return the payload the accepted commit produced.
+     *
+     * AWAITS the commit — the payload exists only once the group takes the attempt
+     * that minted it, and it is deliberately not readable through the control-request
+     * node. So the CALLER MUST BE OUTSIDE any write transaction: the lane's own reads
+     * need that connection.
      *
      * `grants` are stringified write-capability JWTs the caller wants the joiner
      * to hold immediately on join. `revocations` are signed revocation JWTs the
      * caller wants the joiner to apply immediately — only verified ones travel;
      * pending revocations (cap not yet known by the inviter) do not.
      */
-    invite: (groupID: string, joinRequest: string, grants?: Array<string>, revocations?: Array<string>) => Promise<InviteToGroupData>;
+    requestInvite: (input: InviteToGroupInput) => Promise<InviteToGroupData>;
     join: (invitePayload: string, joinRequestPayload: string) => Promise<JoinGroupData>;
     leave: (groupID: string) => Promise<LeaveGroupData>;
-    removeMember: (groupID: string, memberDID: string) => Promise<RemoveGroupMemberData>;
-    update: (input: UpdateGroupInput) => Promise<GroupData>;
-    updateCircle: (input: UpdateCircleInput) => Promise<CircleData>;
+    /**
+     * Request a member's removal, by driving an MLS Remove commit that also
+     * carries the demotion entry an admin's eviction must enact. Authority is the
+     * caller's mirrored admin role, so a non-admin is refused before anything is
+     * written, as is a removal that would leave the group with no admin.
+     */
+    requestRemoveMember: (input: RemoveGroupMemberInput) => Promise<ControlRequestData>;
+    /**
+     * Request a change to the group's settings, by emitting a self-signed
+     * `group.settings` entry that rides an MLS commit. Authority is the caller's
+     * mirrored admin role. An input carrying no field beyond `groupID` is minted
+     * already settled `no_op`.
+     */
+    requestUpdate: (input: UpdateGroupInput) => Promise<ControlRequestData>;
+    /**
+     * Request a change to a circle's definition, by emitting a self-signed
+     * `circle.def` entry that rides an MLS commit. `circle.def` is whole-value LWW,
+     * so the patch is merged over the current definition BEFORE it is signed. An
+     * input carrying no field beyond `circleID` is minted already settled `no_op`.
+     */
+    requestUpdateCircle: (input: UpdateCircleInput) => Promise<ControlRequestData>;
     updateCatalog: (params: {
         catalogID: string;
         name?: string;
         filterCriteria?: string;
     }) => Promise<CatalogData>;
     deleteCatalog: (catalogID: string) => Promise<DeleteCatalogData>;
-    deleteCircle: (circleID: string) => Promise<DeleteCircleData>;
-    removeCircleMember: (circleID: string, memberDID: string) => Promise<RemoveCircleMemberData>;
+    /**
+     * Request that a circle be deleted, by emitting a self-signed `removed`
+     * definition entry that rides an MLS commit. Authority is the caller's mirrored
+     * admin role. A circle already absent or tombstoned is minted settled `no_op`.
+     */
+    requestDeleteCircle: (input: DeleteCircleInput) => Promise<ControlRequestData>;
+    /**
+     * Request that a DID be removed from a circle, by emitting a self-signed
+     * `removed` membership entry that rides an MLS commit. Same authority as
+     * {@link GroupRequestContext.requestDeleteCircle}. A DID that is not an active
+     * member settles `no_op`.
+     */
+    requestRemoveCircleMember: (input: RemoveCircleMemberInput) => Promise<ControlRequestData>;
     /**
      * Mint a `document/write` capability granting `to` write access on resources
      * matching `res`. Token is stored grantor-side, broadcast to the group, and
@@ -196,11 +382,341 @@ export type GroupRequestContext = {
         jti: string;
     }) => Promise<boolean>;
 };
+/**
+ * Result of a `syncPeer` run, mirroring the `SyncPeerPayload` GraphQL type. All
+ * zero when the local device has no active catalog (the opt-in resting state):
+ * a clean no-op, never an error.
+ */
+export type SyncPeerData = {
+    messagesReceived: number;
+    messagesSent: number;
+    divergentBuckets: number;
+};
+/**
+ * Why an automatic catch-up carried nothing — the distinction all-zero counts
+ * cannot draw, and the one a screen has to draw to say anything true.
+ *
+ * - `synced` — a session ran. Zero counts here mean the two devices agreed.
+ * - `no-scopes` — this device has activated no catalog. Nothing was attempted,
+ *   and nothing is wrong: the opt-in resting state.
+ * - `no-candidates` — no co-member has ever announced merkle catch-up in this
+ *   group. Peering is incomplete, or nobody else has come online yet.
+ * - `no-route` — candidates existed and none answered. Every one was tried.
+ */
+export type PeerCatchUpOutcome = 'synced' | 'no-scopes' | 'no-candidates' | 'no-route';
+/**
+ * What an automatic catch-up did, and — the part a caller cannot infer — WHICH
+ * peer the ranking picked. `peerDID` names the peer a session ran against, the
+ * last one tried when none answered, and `null` when none was tried at all.
+ *
+ * Read {@link outcome}, never the counts: three different situations produce
+ * all-zero, and only one of them is a device that is up to date.
+ */
+export type PeerCatchUpData = SyncPeerData & {
+    peerDID: string | null;
+    outcome: PeerCatchUpOutcome;
+    /**
+     * Why the last candidate failed, when the outcome is `no-route`. Absent for
+     * every other outcome, and for a `no-route` whose failure carried no message.
+     *
+     * `no-route` on its own cannot separate a device that is switched off from a
+     * session that connected, was answered, and then starved — two states that
+     * want opposite responses from whoever reads them. The failure the loop
+     * already catches is the only thing that tells them apart, and it used to be
+     * dropped after a debug line.
+     */
+    failureReason?: string;
+};
 export type SyncRequestContext = {
     addPeer: (config: PeerConfig) => Promise<void>;
     removePeer: (peerDID: string) => Promise<void>;
     listPeers: () => Promise<Array<PeerConfigWithID>>;
     getStatus: (peerDID?: string) => SyncStatus;
+    /**
+     * Run a sync session against one named device, scoped by the local device's
+     * ACTIVE catalogs (resolved via `resolveCatalogSyncScopes`). Zero active
+     * catalogs → an all-zero no-op payload.
+     *
+     * `groupID` picks the ROUTE and nothing else: a co-member is reached through
+     * that group's hub tunnel, falling back to the persisted registry for a peer
+     * added by URL. It does not narrow the scopes — those stay device-wide, which
+     * is what lets one session carry documents belonging to another group.
+     *
+     * Both lookups are persisted, so this works after a restart with no prior
+     * `connectPeer`. The peer is taken as given: a user-named device is served
+     * whatever its availability class says about it, so a phone is never refused.
+     * Unreachable is an error here, not a report — someone asked.
+     */
+    syncPeer: (groupID: string, peerDID: string) => Promise<SyncPeerData>;
+    /**
+     * Run the same session against the best candidate the group's discovery
+     * projection offers — availability tier first, most recently applied
+     * announcement breaking ties — over the same scopes {@link syncPeer} uses.
+     *
+     * Walks down the ranking when a candidate does not answer, because a row says
+     * a device once announced and never that it is on. Reports {@link
+     * PeerCatchUpData.outcome} rather than throwing: nobody named these peers, so
+     * nobody is waiting to be told which of them was off.
+     *
+     * No trigger and no timer: the caller decides WHEN (a foreground, a hub
+     * connect, a detected gap), and this decides only WHO.
+     */
+    catchUpWithBestPeer: (groupID: string) => Promise<PeerCatchUpData>;
+    /**
+     * Every co-member device this one has ever heard announce in the group.
+     *
+     * The PROJECTION, not a gather: a row records that a device once said what it
+     * is, and rows are never deleted on silence. So this is "what is known", and
+     * a gather is what annotates it with "and who answered just now" — a screen
+     * built on the gather alone shows a device disappearing every time it sleeps.
+     *
+     * Includes this device's own row, because the projection holds it and hiding
+     * it here would make the list disagree with the store for one DID. Callers
+     * rendering "my other devices" filter it out.
+     */
+    listPeerDevices: (groupID: string) => Promise<Array<PeerDeviceData>>;
+};
+/** One device's last word about itself, as the projection holds it. */
+export type PeerDeviceData = {
+    peerDID: string;
+    /** Self-declared display hint, rendered beside the DID and never read as one. */
+    label: string;
+    availability: string;
+    capabilities: Array<PeerCapability>;
+    /** The announcer's own stamp, which the row is LWW-keyed by. */
+    hlc: string;
+};
+export type RemoteGroupInfoData = {
+    id: string;
+    name: string;
+};
+export type PeerInfoData = {
+    did: string;
+    endpoint: string;
+    groups: Array<RemoteGroupInfoData>;
+};
+/**
+ * Per-model outcome of an outbound share, mirroring the `CircleModelAccess`
+ * GraphQL enum. Reported only for the models the user explicitly listed in
+ * `send.models`. High-level ops write only fresh rows — an existing default is
+ * reported, never widened.
+ */
+export type CircleModelAccess = 'MODEL_GRANTED' | 'MODEL_PRE_EXISTING' | 'DOCUMENT_ONLY';
+export type ModelShareResultData = {
+    modelID: string;
+    access: CircleModelAccess;
+};
+export type SharePeerGroupParams = {
+    peerDID: string;
+    /** Share an existing local group. Mutually exclusive with `name`. */
+    groupID?: string | null;
+    /** Create a new group with this name. Mutually exclusive with `groupID`. */
+    name?: string | null;
+    /**
+     * The user's exact model selection from the share dialog. `null` = no send
+     * leg: no catalog is created and no default rows are written (plumbing only).
+     * An entry per listed model is returned in `modelAccess`.
+     */
+    sendModels?: Array<string> | null;
+    /**
+     * Opt the sharer into pulling the share scope: the share circle's catalog is
+     * activated (created active with a fresh `send`, or an existing catalog flipped
+     * active when re-sharing an already-configured group). Default `false` — the
+     * catalog is created known and the sharer configures pulling later.
+     */
+    receiveActivate: boolean;
+    /**
+     * Write the owner's read model-default naming the share circle, through the
+     * engine's owner-signed access-default executor. Bound by the resolver to
+     * `context.executeSetModelAccessDefaults` so `engine:access-default:set` fires
+     * and broadcast/invite seeding stay consistent. Called only for MODEL_GRANTED.
+     */
+    setReadDefaultForCircle: (modelID: string, circleID: string) => Promise<void>;
+};
+export type SharePeerGroupData = {
+    group: GroupData;
+    modelAccess: Array<ModelShareResultData>;
+    /** The share circle's catalog, or null when no `send` leg created/reused one. */
+    catalogID: string | null;
+};
+export type AdmitJoinRequestParams = {
+    /** The group to admit into. It must already exist on this device. */
+    groupID: string;
+    /**
+     * The join request its author emitted, verbatim. UNTRUSTED: nothing signed the
+     * hand-off, so the joiner's DID comes from the KeyPackage credential and the
+     * payload's own `did` field is only cross-checked against it.
+     */
+    joinRequest: string;
+    /** See {@link SharePeerGroupParams.sendModels}. */
+    sendModels?: Array<string> | null;
+    /** See {@link SharePeerGroupParams.receiveActivate}. */
+    receiveActivate: boolean;
+    /** See {@link SharePeerGroupParams.setReadDefaultForCircle}. */
+    setReadDefaultForCircle: (modelID: string, circleID: string) => Promise<void>;
+};
+export type AdmitJoinRequestData = SharePeerGroupData & {
+    /** The admitted DID, derived from the join request's KeyPackage credential. */
+    peerDID: string;
+    /**
+     * The invite the joiner completes with. Carries the designation above, so a
+     * joiner that completes it lands in the share circle already.
+     */
+    invitePayload: string;
+};
+export type JoinPeerGroupParams = {
+    peerDID: string;
+    /** The group to join, as discovered from the peer's `connectPeer` group list. */
+    groupID: string;
+};
+/** The read access-rule fields a `setCircleSync` add/remove writes for a model. */
+export type SetReadDefaultParams = {
+    modelID: string;
+    accessLevel: AccessLevel;
+    allowedDIDs: Array<string> | null;
+    allowedCircles: Array<string> | null;
+    allowedGroups: Array<string> | null;
+};
+export type SetCircleSyncParams = {
+    circleID: string;
+    /**
+     * `true` activates every catalog in the circle; `false` deactivates them all;
+     * `null` leaves activation untouched. Purely local — no entry, no broadcast.
+     */
+    pull: boolean | null;
+    /**
+     * The caller's desired sharing END STATE into this circle. `{ models }` makes
+     * the caller's read defaults naming the circle become EXACTLY these models
+     * (`[]` stops sharing entirely); `null` leaves sharing untouched.
+     */
+    share: {
+        models: Array<string>;
+    } | null;
+    /**
+     * Owner-signed read access-default writer. Bound by the resolver to
+     * `context.executeSetModelAccessDefaults` (permissionType `read`) so
+     * `engine:access-default:set` fires and the broadcast/push seeding stay
+     * consistent. Only ever writes the caller's own rows.
+     */
+    setReadDefault: (params: SetReadDefaultParams) => Promise<void>;
+    /**
+     * Owner-signed read access-default remover. Bound by the resolver to
+     * `context.executeRemoveModelAccessDefaults(modelID, ['read'])` so
+     * `engine:access-default:removed` fires and the removal broadcasts. Used when
+     * dropping the circle empties a restricted rule of every grantee.
+     */
+    removeReadDefault: (modelID: string) => Promise<void>;
+};
+/**
+ * A circle the device can reach, carrying THIS device's sync state for it.
+ * Computed from local state alone (no wire entry, no network round-trip), and by
+ * one shared helper, so the join-time picker, the `circleSync` query, and
+ * `setCircleSync`'s post-state cannot drift from one another.
+ */
+export type CircleSyncStateData = {
+    id: string;
+    groupID: string;
+    name: string;
+    description: string;
+    /** The circle's catalog IDs (the scope a pull activates together). */
+    catalogIDs: Array<string>;
+    /** Admin-authored: every group member reaches an open circle implicitly. */
+    open: boolean;
+    /**
+     * True only when the circle has at least one catalog AND every one is active
+     * on this device — the post-state of a pull that activates all the circle's
+     * catalogs together (and a pull-off that deactivates them all inverts). A
+     * zero-catalog circle has nothing to pull, so it is false.
+     */
+    pulling: boolean;
+    /**
+     * Models this device shares INTO the circle: its OWN read access-default rows
+     * whose `allowedCircles` names this circle. Write defaults are excluded.
+     */
+    sharing: Array<string>;
+};
+export type JoinPeerGroupData = {
+    group: GroupData;
+    /**
+     * Catalogs seeded (or already known) for this group — the group's circles'
+     * catalog IDs present locally. Apps render the receive side of the share
+     * settings from these; they are activated only behind `receiveActivate`.
+     */
+    knownCatalogIDs: Array<string>;
+    /**
+     * True when this device already held the full local group state (MLS state +
+     * own membership row) and the dance was skipped entirely, so the app can
+     * inform the user the group was already joined.
+     */
+    alreadyJoined: boolean;
+    /**
+     * The group's OPEN circles with this device's current `pulling` / `sharing`,
+     * so the app can render an opt-in picker. Open circles only — a closed circle
+     * the device holds a grant for is not a user opt-in and is excluded.
+     */
+    openCircles: Array<CircleSyncStateData>;
+};
+export type PeerRequestContext = {
+    /**
+     * Discover a peer at `url` (GET `/info`), validate it advertises the sync +
+     * peer protocols, open an Enkaku peer client with the engine identity, fetch
+     * the remote DID + groups via `peer/groups`, and hold the connection in
+     * memory keyed by the remote DID. Persists nothing durable.
+     */
+    connect: (url: string) => Promise<PeerInfoData>;
+    /**
+     * Compose the outbound share. Plumbing always: create/reuse a group, a share
+     * circle scoped to both DIDs, run the MLS invite dance over the held peer
+     * connection, register the sync peer. Access legs only from an explicit
+     * `sendModels`: a catalog over exactly those models plus fresh read model
+     * defaults naming the share circle (activated per `receiveActivate`). No send
+     * = no catalog, no rows. Every step is idempotent so a retry after a mid-flow
+     * failure no-ops the completed steps.
+     */
+    sharePeerGroup: (params: SharePeerGroupParams) => Promise<SharePeerGroupData>;
+    /**
+     * Admit the author of a join request into an existing group from local state
+     * alone — no peer connection is opened, read, or required. Designates the
+     * joiner's access exactly as `sharePeerGroup` does (the same function), then
+     * mints the invite that snapshots it, for the operator to carry to the joiner
+     * by whatever means it has.
+     *
+     * The admitted DID comes from the join request's KeyPackage credential, and a
+     * payload whose plaintext `did` disagrees with it is refused. A DID already in
+     * the MLS roster is also refused — never evicted, which is what the connected
+     * path does on the strength of a signature this one does not have.
+     */
+    admitJoinRequest: (params: AdmitJoinRequestParams) => Promise<AdmitJoinRequestData>;
+    /**
+     * Compose the inbound join. Plumbing only: mint a KeyPackage bundle, pull an
+     * invite from the held peer via the `group/invite` procedure, complete the
+     * MLS join (seeding ledger/circles/access-defaults/catalogs from the invite
+     * payload as KNOWN), register the sync peer, and trigger a ledger-catchup
+     * backstop. It writes no access rows, activates nothing, and runs no sync —
+     * the user opts into what to send/receive afterward via the explicit surfaces.
+     * The dance is skipped (and `alreadyJoined` reported) only when the device
+     * holds the full local group state — MLS state + own membership row; every
+     * step is idempotent so a retry re-runs the legs as no-ops and heals a partial
+     * run.
+     */
+    joinPeerGroup: (params: JoinPeerGroupParams) => Promise<JoinPeerGroupData>;
+    /**
+     * Apply one circle's desired sync end state idempotently, gated on the
+     * caller's own access to the circle. `pull` toggles local catalog activation;
+     * `share` makes the caller's sharing into the circle become EXACTLY
+     * `share.models` via a read-modify-write diff over the caller's own read
+     * defaults. Local pull first, then the share rows, then a delivery-guarantee
+     * push of the shared models' SET rows to the group's connected in-group peers.
+     * Every step is idempotent so a partial run heals on retry.
+     */
+    setCircleSync: (params: SetCircleSyncParams) => Promise<CircleSyncStateData>;
+    /**
+     * Every circle in the group this device can currently reach — explicitly or
+     * through the open arm — with this device's `pulling` / `sharing` for each. The
+     * read path behind the join-time picker: an app re-reads it to pick up a circle
+     * the admin opened or closed since the join.
+     */
+    listCircleSyncStates: (groupID: string) => Promise<Array<CircleSyncStateData>>;
 };
 export type P2PJoinRequestContext = {
     prepareRequest: () => Promise<{
@@ -291,6 +807,7 @@ export type P2PContext = {
     join: P2PJoinRequestContext;
     hub: HubRequestContext;
     delegation: DelegationRequestContext;
+    peer: PeerRequestContext;
 };
 declare module '@kubun/graphql' {
     interface PluginContextMap {
@@ -326,12 +843,87 @@ export type GroupHealthSnapshot = {
 export type RejoinResult = {
     status: 'recovered' | 'recovery-failed';
 };
+/** Tuning for a ledger catch-up gather round-trip. */
+export type LedgerCatchupOptions = {
+    /**
+     * Per-hub gather timeout in milliseconds. Omitted uses the broadcast client's
+     * own default. The gather always waits the full window unless `quorum` caps it.
+     */
+    timeoutMs?: number;
+    /** Resolve a hub's gather as soon as this many replies arrive. */
+    quorum?: number;
+};
+/** What a ledger catch-up round-trip folded into the local ledger. */
+export type LedgerCatchupSummary = {
+    /**
+     * Size of the ledger adopted from the one accepted reply.
+     *
+     * NOT a count of what was new: a gather installs a whole ledger over whatever
+     * was held, so "new" is not a question it can answer — re-running a catch-up
+     * that changes nothing still reports the full size. Zero means no responder's
+     * ledger was accepted, which `responders` distinguishes from no responder at
+     * all.
+     */
+    applied: number;
+    /** Entries dropped because their signed token failed verification. */
+    rejected: number;
+    /** Replies considered, refused ones included (a member on two hubs counts twice). */
+    responders: number;
+};
+/**
+ * What this device says about itself on a group's peer lane. No DID: the
+ * announcer is the frame's MLS-authenticated sender, resolved by the receiver's
+ * own lane, so there is nothing here for a caller to claim to be.
+ */
+export type LocalPeerAnnouncement = {
+    /** Display hint only — a device name, never an identity. */
+    label: string;
+    availability: PeerAvailability;
+    capabilities: Array<PeerCapability>;
+};
+/**
+ * One device that ANSWERED a gather, inside the window. Not a member list: a
+ * co-member that was asleep is absent from this and keeps its projection row.
+ */
+export type GatheredPeer = LocalPeerAnnouncement & {
+    /** The MLS-authenticated responder. Never anything the reply body claimed. */
+    peerDID: string;
+    /** The responder's own stamp, the same one its projection row is keyed by. */
+    hlc: string;
+};
+export type PeerGatherOptions = {
+    /**
+     * Only devices answering one of these protocols reply. Omitted means any.
+     * Filtering at the responder is what bounds a gather in a large group — and it
+     * is what makes a future WebRTC query return the offer-capable subset for free.
+     */
+    protocols?: Array<string>;
+    /** How long to hold the window open. The gather always costs its full window unless `quorum` closes it. */
+    timeoutMs?: number;
+    /**
+     * Close a hub's window as soon as this many distinct devices have answered
+     * SUCCESSFULLY — a declined reply is dropped before it is counted, so a target
+     * that includes a device which cannot answer is a target that is never met.
+     * Counted per hub, then de-duplicated by DID across hubs afterwards.
+     *
+     * Omitted means every device this group's projection holds that advertises a
+     * matching capability, so a gather ends when the last one that could answer
+     * has. Pass a number to ask for less.
+     */
+    quorum?: number;
+};
+/**
+ * Why a presence announce/gather ran. Log-only: it names the trigger for a reader
+ * of the logs, and nothing branches on it.
+ */
+export type PresenceReason = 'hub-connected' | 'epoch-changed' | 'app-window-pruned' | 'requested';
 export type SyncPluginAPI = {
     /** Resolves when the HTTP sync transport is registered (only present when http option is enabled). */
     syncReady?: Promise<void>;
     /**
-     * Resolves when hub relay setup completes. `DISABLED_HUB.ready` is already
-     * resolved when the `hub` plugin option is absent.
+     * Resolves when hub relay setup completes. The relay always runs — it is what
+     * gives each joined group its commit lane — so this resolves regardless of
+     * whether the `hub` plugin option is set.
      */
     hubReady: Promise<void>;
     addPeer(config: PeerConfig): Promise<void>;
@@ -345,7 +937,86 @@ export type SyncPluginAPI = {
         direction?: SyncDirection;
     }): Promise<SyncSessionResult>;
     getStatus(peerDID?: string): SyncStatus;
+    /**
+     * Catch up with the best candidate one group's discovery projection offers, over
+     * the local device's active-catalog scopes. See
+     * {@link SyncRequestContext.catchUpWithBestPeer} — the host decides when, this
+     * decides who, and an explicit `syncPeer` ignores the ranking entirely.
+     */
+    catchUpWithBestPeer(groupID: string): Promise<PeerCatchUpData>;
+    /**
+     * Every device this one has heard announce in the group — the projection, and
+     * never a liveness answer. {@link SyncPluginAPI.gatherPeers} is what says who
+     * is reachable now; a screen needs both, and the two are different questions.
+     */
+    listPeerDevices(groupID: string): Promise<Array<PeerDeviceData>>;
     onSyncEvent(callback: (event: SyncEvent) => void): () => void;
+    /**
+     * Subscribe to hub identity changes. A hub whose signing key rotated is
+     * reconnected to under its new DID without the application doing anything —
+     * this is how it learns that happened. Returns the unsubscribe.
+     */
+    onHubServerDIDChanged(listener: (data: HubServerDIDChangedData) => void): () => void;
     /** Create a sync-specific transport for direct in-process connections. */
     createSyncTransport(signal?: AbortSignal): ClientTransportOf<SyncProtocol>;
+    /**
+     * Ask the group's current members for the full control ledger and fold any
+     * missing entries locally. Backfills entries an invite snapshot missed (or a
+     * member missed while its peer was offline); every token self-authenticates,
+     * so the responders are untrusted and duplicates are idempotent no-ops. A
+     * no-op (all-zero summary) when no `hub` option is configured.
+     */
+    requestLedgerCatchup(groupID: string, options?: LedgerCatchupOptions): Promise<LedgerCatchupSummary>;
+    /**
+     * Declare what this device IS — its display label, its availability class and
+     * the capabilities it answers — and advertise it to every group it belongs to.
+     * THE one way to advertise: there is no per-group or bodies-only variant.
+     *
+     * This is the "local capability or label change" trigger: the host calls it when
+     * either changes, and every group hears the new shape without the host tracking
+     * which groups exist. The profile is durable, so every other trigger (a hub
+     * connect, an epoch rotation, a pruned app window) has something to announce
+     * after a restart. A device that never calls this advertises NOTHING — no label
+     * is invented for it, and it stays invisible to its co-members' discovery.
+     *
+     * Resolves once each group's frame is sealed and sent. A group with no live hub
+     * peer is a no-op rather than a throw, matching every other broadcast.
+     */
+    setLocalPeerProfile(profile: LocalPeerAnnouncement): Promise<void>;
+    /** What this device last declared itself to be, or `null` if it never has. */
+    getLocalPeerProfile(): Promise<LocalPeerAnnouncement | null>;
+    /**
+     * Ask a group's members who is reachable RIGHT NOW, optionally narrowed to
+     * devices answering named protocols, and fold every answer into the projection.
+     *
+     * THE RESULT IS "WHO ANSWERED WITHIN THE WINDOW", NEVER "WHO EXISTS". A device
+     * that was asleep is absent from it and keeps its projection row untouched;
+     * only a roster removal deletes a row. Surfacing this as a member list is how
+     * an empty result comes to read as "my laptop was removed from the group".
+     */
+    gatherPeers(groupID: string, options?: PeerGatherOptions): Promise<Array<GatheredPeer>>;
+    /**
+     * Announce this device and gather its co-members, in that order — what a host
+     * calls when it comes to the foreground. The same pair the hub-connect and
+     * pruned-window triggers run internally.
+     */
+    refreshPeerPresence(groupID: string, options?: PeerGatherOptions): Promise<Array<GatheredPeer>>;
+    /**
+     * Try this device's hubs now instead of waiting out the reconnect backoff, and
+     * answer with whether any is connected afterwards.
+     *
+     * The backoff climbs to half a minute, which is the right cost for a device
+     * nobody is watching and the wrong one for a person who has just started their
+     * hub and is looking at the screen. Wire this to whatever that person presses.
+     * `false` means the attempt was made and did not connect — the automatic
+     * retries carry on either way.
+     */
+    retryHubConnection(): Promise<boolean>;
+    /**
+     * Look up the live in-memory connection to a peer, keyed by remote DID.
+     * Present only after a successful `connectPeer`; the later dance ops
+     * (`joinPeerGroup` / `sharePeerGroup`) dispatch their peer procedures over
+     * this held connection.
+     */
+    getPeerConnection(peerDID: string): PeerConnection | undefined;
 };