@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/context/peer.js

@@ -0,0 +1,1216 @@
+import { Client } from '@enkaku/client';
+import { ClientTransport } from '@enkaku/http-fetch';
+import { normalizeDID } from '@kokuin/token';
+import { getGraphStore } from '@kubun/store-graph';
+import { getP2PStore } from '@kubun/store-p2p';
+import { readGroupAnchor } from '@kumiai/mls';
+import { blake3 } from '@noble/hashes/blake3.js';
+import { GraphQLError } from 'graphql';
+import { signAccessDefaultSet } from '../groups/access-default-token.js';
+import { applyAccessDefaultSetFrame } from '../groups/broadcast.js';
+import { foldGroupSettings } from '../groups/circle-projection.js';
+import { awaitControlRequestSettled } from '../groups/control-request.js';
+import { resolveJoinRequestDID } from '../groups/join-request-identity.js';
+import { SyncAccessDeniedError } from '../sync/errors.js';
+import { createGroupContext } from './group.js';
+import { createJoinContext } from './join.js';
+import { requireGroupAdmin } from './require-admin.js';
+import { toISO } from './types.js';
+/**
+ * Deterministic name marking the circle a prior `sharePeerGroup` created.
+ *
+ * One share circle per (group, SHARER), not per peer. A per-peer circle put a
+ * new circle in the model's read default on every admission, and that default is
+ * never widened once it exists — so the second device admitted to a group landed
+ * outside the ACL and could read nothing by model, while the admission reported
+ * a share. Sharing into one circle means the circle the first share named is
+ * already there, and nothing has to widen an ACL to admit a device.
+ *
+ * Keyed on the sharer because sharing is per-direction: each device owns the
+ * circle for what IT sends, and two admins deriving one id would merge two
+ * access scopes (see {@link shareRowID}).
+ */ function shareCircleName(ownerDID) {
+    return `peer-share:${ownerDID}`;
+}
+/**
+ * How long the re-invite path waits for a stale leaf's eviction to land before
+ * refusing the invite.
+ *
+ * Sized for the commit lane, not for a local write: the Remove goes to the
+ * group's commit log and can be rebased by a concurrent commit before it is
+ * accepted, so the bound has to cover several attempts plus their round-trips.
+ * It is a refusal deadline, not a latency target — a rejoin that waits this long
+ * has hit a real fault, and the caller can retry.
+ */ const EVICT_STALE_LEAF_TIMEOUT = 30_000;
+/**
+ * How long one `sharePeerGroup` step waits for the commit carrying its entry to
+ * be enacted. A hub round trip inside an interactive share flow — generous
+ * enough that a healthy hub never trips it, short enough that a share does not
+ * hang a UI. Applied per step, not as one shared budget.
+ */ const SHARE_STEP_TIMEOUT_MS = 10_000;
+/**
+ * Derive a stable UUID for one of the rows `sharePeerGroup` owns, from the
+ * (group, sharer) pair the share is made FROM and a per-row `slot`.
+ *
+ * DERIVED so a retried step re-mints the SAME subject — `circle.def`'s whole-value
+ * LWW folds that as an update — instead of a second circle and a second catalog.
+ * A second peer admitted to the same group derives the same pair, which is the
+ * point: it joins the circle the first share created.
+ *
+ * NOT caller-supplied, and NOT keyed on the group alone: two admins picking one
+ * id would merge two access scopes, and since a member subject embeds the circle
+ * id, both admins' grants would land in the merged scope with nothing thrown.
+ * Keying on the sharer is safe because a collision then MEANS this device's own
+ * share circle for that group.
+ *
+ * blake3 for the React Native / browser / node triple.
+ */ function shareRowID(slot, groupID, ownerDID) {
+    const digest = blake3(new TextEncoder().encode(`kubun.peer-share:${slot}:${groupID}:${ownerDID}`), {
+        dkLen: 16
+    });
+    // Format as a v4-shaped UUID: every other id in the tree comes from
+    // `getRandomID()`, which yields v4, and columns and callers assume that shape.
+    // The version and variant nibbles are overwritten rather than derived, so the
+    // string is a well-formed UUID that carries 122 bits of the digest.
+    const bytes = Uint8Array.from(digest);
+    bytes[6] = bytes[6] & 0x0f | 0x40;
+    bytes[8] = bytes[8] & 0x3f | 0x80;
+    const hex = Array.from(bytes, (b)=>b.toString(16).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32)
+    ].join('-');
+}
+/**
+ * Models this device shares INTO a circle: its OWN read access-default rows
+ * whose `allowedCircles` names the circle. Write defaults are excluded — sharing
+ * is letting the circle READ your docs. Shared by the join-time open-circle
+ * picker and `setCircleSync`'s payload so the two computations cannot drift.
+ */ function circleSharing(ownDefaults, circleID) {
+    return ownDefaults.filter((row)=>row.permissionType === 'read' && (row.allowedCircles ?? []).includes(circleID)).map((row)=>row.modelID);
+}
+/**
+ * Catalog reads for one flow, cached by id.
+ *
+ * The cache holds the PROMISE, not the awaited row: caching the row leaves a
+ * window where concurrent loads of the same id all miss and each issue their own
+ * read, so the cache silently stops working the moment a caller stops awaiting
+ * in sequence.
+ */ function createCatalogLoader(graphStore) {
+    const cache = new Map();
+    return {
+        async prime (ids) {
+            const missing = ids.filter((id)=>!cache.has(id));
+            if (missing.length === 0) {
+                return;
+            }
+            const found = await graphStore.getCatalogs(missing);
+            // Seed misses too, so a catalog this device does not hold is remembered as
+            // absent rather than re-queried per lookup.
+            for (const id of missing){
+                cache.set(id, Promise.resolve(found.get(id)));
+            }
+        },
+        load (id) {
+            const cached = cache.get(id);
+            if (cached != null) {
+                return cached;
+            }
+            const pending = graphStore.getCatalog(id);
+            cache.set(id, pending);
+            return pending;
+        }
+    };
+}
+/**
+ * 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 (a pull-off deactivating them all inverts it). A zero-catalog
+ * circle has nothing to pull, so it is false.
+ */ async function circlePulling(catalogIDs, loadCatalog) {
+    if (catalogIDs.length === 0) {
+        return false;
+    }
+    for (const catalogID of catalogIDs){
+        const catalog = await loadCatalog(catalogID);
+        if (catalog?.active !== 1) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Own access-default rows keyed `modelID:permissionType`, for point lookups. */ function indexDefaults(rows) {
+    return new Map(rows.map((row)=>[
+            `${row.modelID}:${row.permissionType}`,
+            row
+        ]));
+}
+/**
+ * The one circle row + local state → `CircleSyncState` mapping. The join-time
+ * picker, the `circleSync` query, and `setCircleSync`'s post-state all go through
+ * it, so what a mutation returns is exactly what a re-read reports.
+ */ async function circleSyncState(circle, ownDefaults, loadCatalog) {
+    return {
+        id: circle.id,
+        groupID: circle.group_id,
+        name: circle.name,
+        description: circle.description,
+        catalogIDs: circle.catalog_ids,
+        open: circle.open === 1,
+        pulling: await circlePulling(circle.catalog_ids, loadCatalog),
+        sharing: circleSharing(ownDefaults, circle.id)
+    };
+}
+/**
+ * Well-known protocol names advertised in a peer's `/info`. `connectPeer`
+ * requires both: the sync protocol so a later `syncPeer` can reach the data
+ * leg, and the peer protocol to run `peer/groups` (and the dance) now. These
+ * are the default registration names; a peer that advertises the sync protocol
+ * under a custom path is not discoverable by this check.
+ */ const SYNC_PROTOCOL_NAME = 'sync';
+const PEER_PROTOCOL_NAME = 'peer';
+function isPeerInfoResponse(value) {
+    if (value == null || typeof value !== 'object') return false;
+    const candidate = value;
+    return typeof candidate.did === 'string' && typeof candidate.protocols === 'object';
+}
+/**
+ * Fresh-only read-default classification over the exact models the user chose to
+ * send. A model with no existing read default is granted (a fresh row naming the
+ * circles, written through the owner-signed executor callback); an existing
+ * default that already names every circle is `MODEL_PRE_EXISTING`; one that is
+ * missing any is `DOCUMENT_ONLY` — never widened. Only listed models are
+ * classified, so every entry maps to a deliberate user selection.
+ */ async function classifyModelDefaults(params) {
+    const { graphStore, ownerDID, models, circleIDs, setReadDefault } = params;
+    // One list read for every model's current rule. The grants below write only
+    // models that HAVE no rule, and each model is its own row, so no write here
+    // invalidates another model's snapshot.
+    const existingByKey = indexDefaults(await graphStore.listUserModelAccessDefaults(ownerDID));
+    const modelAccess = [];
+    for (const modelID of models){
+        const existing = existingByKey.get(`${modelID}:read`);
+        if (existing == null) {
+            await setReadDefault(modelID);
+            modelAccess.push({
+                modelID,
+                access: 'MODEL_GRANTED'
+            });
+        } else if (circleIDs.every((circleID)=>(existing.allowedCircles ?? []).includes(circleID))) {
+            modelAccess.push({
+                modelID,
+                access: 'MODEL_PRE_EXISTING'
+            });
+        } else {
+            // A default exists without (all of) these circles — never widened.
+            modelAccess.push({
+                modelID,
+                access: 'DOCUMENT_ONLY'
+            });
+        }
+    }
+    return modelAccess;
+}
+/**
+ * The inviter leg of the inbound dance, run on behalf of a verified caller by
+ * the `group/invite` peer handler. It designates NO circle itself: the joiner
+ * lands only in circles the inviter ALREADY designated — a `sharePeerGroup`
+ * pre-add, or an explicit `requestAddCircleMember` — which `collectInviteSeeds`
+ * snapshots from the ledger. Both of those land through an enacted commit, so
+ * by the time a designation is snapshottable here it is already durable. The
+ * invite runs as THIS device's own identity; the caller only supplies the group
+ * and its KeyPackage.
+ */ export async function serveGroupInvite(deps, params) {
+    const { callerDID, groupID, joinRequest } = params;
+    // The caller may only pull an invite for itself: the signed procedure payload
+    // binds `callerDID`, so refuse a join request naming a different recipient — a
+    // trusted peer must not be able to inject a third party into the group.
+    //
+    // Compared against the KeyPackage's own credential rather than the request's
+    // `did` field, so this binds the envelope to the identity that will actually
+    // hold the MLS leaf. Comparing the plaintext field would let a caller present
+    // its own DID beside someone else's KeyPackage and pass a check that looks
+    // like it verified something.
+    const credentialDID = resolveJoinRequestDID(joinRequest);
+    if (normalizeDID(credentialDID) !== normalizeDID(callerDID)) {
+        throw new Error('group/invite: join request DID does not match the authenticated caller');
+    }
+    const groupCtx = createGroupContext({
+        viewerDID: deps.identity.id
+    }, deps);
+    // A caller already in the MLS roster is a joiner that lost its local group
+    // state — re-adding it directly would fail (MLS rejects an Add for a current
+    // member). Its DID is signature-verified by the peer handler, so a re-join
+    // request from the same principal cannot widen access: evict the stale leaf
+    // and fall through to a fresh Add + Welcome (key rotation via the new
+    // KeyPackage) to restore the joiner's liveness.
+    const staleLeafIndex = await deps.registry.readHandle(groupID, (handle)=>handle.findMemberLeafIndex(callerDID), {
+        stores: deps.stores
+    });
+    if (staleLeafIndex != null) {
+        deps.logger.warn('group/invite: re-inviting existing member, evicting stale roster entry', {
+            groupID,
+            callerDID
+        });
+        // The eviction is AWAITED, not fired and forgotten: the Add below frames
+        // against whatever handle it reads, so it must not be built until the Remove
+        // has advanced this device's epoch past the stale leaf — otherwise existing
+        // members receive an Add against an epoch the Remove is still moving. This
+        // handler is not inside the engine's write transaction, so it can wait.
+        const request = await groupCtx.requestRemoveMember({
+            groupID,
+            memberDID: callerDID
+        });
+        const settled = await awaitControlRequestSettled({
+            stores: deps.stores,
+            emitter: deps.emitter,
+            requestID: request.id,
+            timeoutMs: EVICT_STALE_LEAF_TIMEOUT
+        });
+        if (settled.status !== 'committed') {
+            throw new Error(`group/invite: evicting the stale roster entry did not land (${settled.status})`);
+        }
+    }
+    const inviteResult = await groupCtx.requestInvite({
+        groupID,
+        joinRequest
+    });
+    if (inviteResult.invitePayload == null) {
+        // The Add commit is still parked (this device's hub is offline), so there is
+        // no Welcome to hand back yet — the joiner cannot join until it lands. Surface
+        // the pending state as an error the caller retries, rather than passing a null
+        // payload downstream as if the invite had committed.
+        throw new Error(`group/invite: the add commit is still pending (${inviteResult.request.status}) — retry once the inviter is back online`);
+    }
+    return {
+        invitePayload: inviteResult.invitePayload
+    };
+}
+/**
+ * Apply the access-default rows a verified caller pushed for itself, run by the
+ * `group/push-control` peer handler. The source is UNTRUSTED, so the rows apply
+ * sender-bound — a row is kept only when its owner equals the authenticated
+ * caller, on top of the owner-equals-token-issuer check
+ * `applyAccessDefaultSetFrame` already enforces. A caller therefore cannot
+ * inject another owner's sharing policy.
+ *
+ * The caller must additionally be a member of the named group per THIS device's
+ * own membership view. The other remote ledger-ingest path rides the group's hub
+ * topic, whose MLS derivation is an implicit membership perimeter; this
+ * procedure is reachable by any accepted peer, so the perimeter is restated
+ * here. Fail-closed: an unknown group reads as no membership.
+ */ export async function servePushControl(deps, params) {
+    const { callerDID, groupID, accessDefaults } = params;
+    const [p2pStore, graphStore] = await Promise.all([
+        getP2PStore(deps.stores),
+        getGraphStore(deps.stores)
+    ]);
+    if (!await p2pStore.isGroupMember(groupID, callerDID)) {
+        throw new SyncAccessDeniedError('not a group member', `Push control denied: ${callerDID} is not a member of group ${groupID}`);
+    }
+    const callerNormalized = normalizeDID(callerDID);
+    let accessDefaultsApplied = 0;
+    for (const row of accessDefaults){
+        // Caller-binding: a caller may push only its OWN sharing policy. Drop a row
+        // naming a foreign owner before the token check, so a trusted peer cannot
+        // relay a third party's rows into this device.
+        if (normalizeDID(row.ownerDID) !== callerNormalized) {
+            deps.logger.warn('group/push-control: dropped access-default not owned by the caller', {
+                groupID,
+                ownerDID: row.ownerDID,
+                callerDID
+            });
+            continue;
+        }
+        if (await applyAccessDefaultSetFrame({
+            graphStore,
+            frame: row,
+            ...deps.logger != null ? {
+                logger: deps.logger
+            } : {},
+            groupID
+        })) {
+            accessDefaultsApplied++;
+        }
+    }
+    return {
+        accessDefaultsApplied
+    };
+}
+/**
+ * Designate one peer's access to one group: resolve or create the group, fold
+ * the commit-hub designation, find or create the share circle, admit both DIDs,
+ * and write the catalog + read defaults the share's scope rests on.
+ *
+ * Local state only — no peer connection is read or written. Whatever follows a
+ * designation (the MLS dance, registering the sync peer) belongs to the caller,
+ * so admitting a peer without a live connection reuses this rather than copying
+ * it: an invite payload snapshots exactly what these steps wrote, so a second
+ * copy of the seeding order drifts into a joiner landing in no circle, silently.
+ *
+ * The steps are ORDER-dependent — each reads what an earlier one wrote — so the
+ * sequence below is the contract, not an arrangement.
+ */ export async function designatePeerAccess(deps, params) {
+    const { groupCtx, selfDID, peerDID, target, operation, sendModels, receiveActivate } = params;
+    const [p2pStore, graphStore] = await Promise.all([
+        getP2PStore(deps.stores),
+        getGraphStore(deps.stores)
+    ]);
+    // 1. Resolve or create the group. Existing-by-ID is the idempotent reuse;
+    // the `name` path always mints a new group (a retry uses the groupID path).
+    const group = 'name' in target ? await groupCtx.create({
+        name: target.name
+    }) : await (async ()=>{
+        const existing = await groupCtx.get(target.groupID);
+        if (existing == null) {
+            throw new GraphQLError(`${operation.name}: group ${target.groupID} not found`);
+        }
+        return existing;
+    })();
+    const groupID = group.id;
+    // Admin-only gate. Steps 2-3 mint circle-def and circle-member ledger
+    // entries whose folds admit only a ledger admin's issuance; a non-admin
+    // caller's entries are dropped on every peer, and the drop surfaces frames
+    // later as a null projection read-back. Reject here — before any append.
+    // The `name` path is admin by construction (creating a group mirrors the
+    // fresh handle's roster, which names the creator admin from the genesis
+    // anchor), so the check is a tautology there and never false-denies a
+    // fresh group.
+    const anchor = await deps.registry.readHandle(groupID, async (handle)=>readGroupAnchor(handle), {
+        stores: deps.stores
+    });
+    if (anchor == null) {
+        throw new GraphQLError(`${operation.name}: group ${groupID} has no genesis anchor`);
+    }
+    await requireGroupAdmin({
+        store: p2pStore,
+        groupID,
+        did: selfDID,
+        action: operation.adminAction
+    });
+    // Each step below only ASKS — an entry lands when its commit is enacted — and
+    // each later step reads what an earlier one wrote, most sharply the invite the
+    // caller mints afterwards, which snapshots the circle and the ledger into its
+    // payload. So every settle is awaited; without that the joiner arrives in no
+    // circle and nothing throws. Awaiting a settle is only safe outside an engine
+    // write transaction, so every mutation field reaching this function must be
+    // listed in `nonTransactionalMutationFields` — `sharePeerGroup` is — or the
+    // wait deadlocks a single-connection SQLite adapter.
+    //
+    // Per-step timeout rather than one shared budget, so the throw names the step
+    // that stalled — the raw settle error names only an internal request id.
+    const settleStep = async (step, requestID)=>{
+        let settled;
+        try {
+            settled = await groupCtx.awaitSettle(requestID, SHARE_STEP_TIMEOUT_MS);
+        } catch (cause) {
+            // biome-ignore lint/style/useErrorCause: `originalError` is GraphQLError's own cause channel
+            throw new GraphQLError(`${operation.name}: ${step} did not land within ${SHARE_STEP_TIMEOUT_MS}ms — the group may be partially configured; re-run to converge`, {
+                originalError: cause
+            });
+        }
+        // `no_op` is a success: it means the state the step asked for already
+        // held, which is exactly what a re-run should find.
+        if (settled.status !== 'committed' && settled.status !== 'no_op') {
+            throw new GraphQLError(`${operation.name}: ${step} settled ${settled.status}${settled.error == null ? '' : ` — ${settled.error}`}`);
+        }
+    };
+    // 1b. Promote a locally-designated commit hub to a FOLDED designation before
+    // the invite is minted. The bare bind mutation auto-designates a hub on THIS
+    // device only, so a co-member would fall back to its own first-bound hub and
+    // the group could fork; sharing is the first moment a co-member appears, and
+    // the entry must land before the invite step snapshots the ledger. Authors
+    // ONLY when a hub is designated locally AND none is folded yet — the same
+    // check reprojection reads — so a second share authors nothing.
+    const localCommitHub = await p2pStore.getCommitHub(groupID);
+    if (localCommitHub != null) {
+        const ledger = await deps.registry.readHandle(groupID, (handle)=>handle.ledger, {
+            stores: deps.stores
+        });
+        if (foldGroupSettings(ledger, groupID, anchor)?.commitHub == null) {
+            const request = await groupCtx.requestUpdate({
+                groupID,
+                commitHub: localCommitHub.server_did != null ? {
+                    url: localCommitHub.url,
+                    serverDID: localCommitHub.server_did
+                } : {
+                    url: localCommitHub.url
+                }
+            });
+            await settleStep('designating the commit hub', request.id);
+        }
+    }
+    // 2. Find or create the share circle. Its id is DERIVED from the (group,
+    // sharer) pair, so a run that timed out and then landed is rediscovered
+    // exactly rather than duplicated, and a second peer joins the circle the
+    // first share created — the name is a human-readable marker only, and is
+    // no longer what the lookup keys on.
+    const circleName = shareCircleName(selfDID);
+    const circleID = shareRowID('circle', groupID, selfDID);
+    const existingCircle = await p2pStore.getCircle(circleID);
+    if (existingCircle == null) {
+        const created = await groupCtx.requestCreateCircle({
+            groupID,
+            circleID,
+            name: circleName,
+            description: 'Share circle created by sharePeerGroup'
+        });
+        await settleStep('creating the share circle', created.request.id);
+    }
+    // 3. Add both DIDs to the circle before the invite, so the invite payload
+    // seeds the joiner's circle membership. Skip a DID already an ACTIVE member:
+    // `getCircleMember` answers with tombstoned rows too, and treating one as
+    // present skips the re-add, so a peer removed from this circle once is shared
+    // with again and still cannot read.
+    for (const did of [
+        selfDID,
+        peerDID
+    ]){
+        const member = await p2pStore.getCircleMember(circleID, did);
+        if (member == null || member.removed_at_hlc != null) {
+            const request = await groupCtx.requestAddCircleMember({
+                circleID,
+                memberDID: did,
+                role: 'member'
+            });
+            await settleStep(`adding ${did} to the share circle`, request.id);
+        }
+    }
+    // 4. Access legs come ONLY from an explicit `send`. With no send, the share
+    // is plumbing only: no catalog, no default rows. The catalog + defaults are
+    // written BEFORE the dance so they travel in the invite payload's seeds.
+    const circleRow = await p2pStore.getCircle(circleID);
+    let catalogID = circleRow?.catalog_ids?.[0] ?? null;
+    let modelAccess = [];
+    if (sendModels != null) {
+        if (catalogID == null) {
+            // Derived for the same reason as the circle: a run that created the
+            // catalog but never landed the attachment must reuse it, not mint a
+            // second one. The catalog row itself is a plain store write, so the
+            // probe is the row, not a request.
+            const derivedCatalogID = shareRowID('catalog', groupID, selfDID);
+            const existingCatalog = await graphStore.getCatalog(derivedCatalogID);
+            if (existingCatalog == null) {
+                const filterCriteria = {
+                    models: sendModels,
+                    circles: [
+                        circleID
+                    ]
+                };
+                await groupCtx.createCatalog({
+                    catalogID: derivedCatalogID,
+                    name: circleName,
+                    filterCriteria: JSON.stringify(filterCriteria)
+                });
+            }
+            catalogID = derivedCatalogID;
+            const request = await groupCtx.requestUpdateCircle({
+                circleID,
+                catalogIDs: [
+                    catalogID
+                ]
+            });
+            await settleStep('attaching the catalog to the share circle', request.id);
+            // The catalog is created active (own-catalog default); activation is now
+            // the explicit receive opt-in, so demote it to known unless the sharer
+            // opted into pulling the share scope.
+            if (!receiveActivate) {
+                await graphStore.setCatalogActive(catalogID, false);
+            }
+        } else {
+            // The group's one catalog already exists, and its criteria are what every
+            // member of the share circle pulls. A model outside it would be granted a
+            // read default here and named by no catalog — a share reported as
+            // succeeding that moves nothing — so widen the catalog to cover it.
+            //
+            // Through `updateCatalog` for its two guarantees: it refuses a catalog
+            // this device does not own, and it re-signs the record. Without the
+            // re-sign the widened catalog would stop seeding into invites entirely.
+            //
+            // Group-wide by nature — every device that activated this catalog now
+            // pulls the added models too. That is bounded by each owner's own read
+            // rules, which the catalog selects within and never grants: an undeclared
+            // model defaults to `only_owner` and is not broadcast at all. And it is a
+            // deliberate admin act, since `sharePeerGroup` is admin-gated.
+            const existingCatalog = await graphStore.getCatalog(catalogID);
+            if (existingCatalog == null) {
+                throw new GraphQLError(`sharePeerGroup: the share circle names catalog ${catalogID}, which this device does not hold`);
+            }
+            const covered = existingCatalog.filter_criteria?.models ?? [];
+            const uncovered = sendModels.filter((modelID)=>!covered.includes(modelID));
+            if (uncovered.length > 0) {
+                await groupCtx.updateCatalog({
+                    catalogID,
+                    filterCriteria: JSON.stringify({
+                        ...existingCatalog.filter_criteria,
+                        models: [
+                            ...covered,
+                            ...uncovered
+                        ]
+                    })
+                });
+            }
+            if (receiveActivate) {
+                await graphStore.setCatalogActive(catalogID, true);
+            }
+        }
+        // Fresh-only read defaults for exactly the user's selection.
+        modelAccess = await classifyModelDefaults({
+            graphStore,
+            ownerDID: selfDID,
+            models: sendModels,
+            circleIDs: [
+                circleID
+            ],
+            setReadDefault: (modelID)=>params.setReadDefaultForCircle(modelID, circleID)
+        });
+    } else if (receiveActivate && catalogID != null) {
+        // No send, but the sharer opts into pulling an already-configured group's
+        // existing catalogs.
+        await graphStore.setCatalogsActive(circleRow?.catalog_ids ?? [], true);
+    }
+    return {
+        group,
+        modelAccess,
+        catalogID
+    };
+}
+export function createPeerContext(ctx, deps) {
+    return {
+        connect: async (url)=>{
+            // Discover the peer: GET `/info`, which advertises the device DID and the
+            // protocol paths it serves. A server-side outbound fetch to a
+            // caller-supplied URL is accepted — the caller is the device operator.
+            const infoURL = new URL('/info', url).toString();
+            let info;
+            try {
+                const response = await deps.runtime.fetch(infoURL);
+                if (!response.ok) {
+                    throw new Error(`peer /info responded with status ${response.status}`);
+                }
+                const body = await response.json();
+                if (!isPeerInfoResponse(body)) {
+                    throw new Error('peer /info returned an unexpected shape');
+                }
+                info = body;
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`connectPeer: failed to reach ${infoURL}: ${message}`, {
+                    cause: error
+                });
+            }
+            // Both protocols must be advertised: the peer leg (used now) and the sync
+            // leg (used by a later `syncPeer`).
+            const peerPath = info.protocols[PEER_PROTOCOL_NAME];
+            const syncPath = info.protocols[SYNC_PROTOCOL_NAME];
+            if (peerPath == null || syncPath == null) {
+                throw new Error(`connectPeer: ${url} does not advertise the required protocols (need '${SYNC_PROTOCOL_NAME}' and '${PEER_PROTOCOL_NAME}')`);
+            }
+            // Resolved against the URL the operator gave, and pinned to its origin. The
+            // `/info` body is an unauthenticated fetch, so an absolute URL in it would
+            // silently move the connection — and the sync leg, which `addPeer`
+            // persists — to a host the operator never named. A protocol entry is a
+            // path on the peer being connected to; anything else is refused rather
+            // than followed.
+            const resolveEndpoint = (path, protocol)=>{
+                const base = new URL(url);
+                const resolved = new URL(path, base);
+                if (resolved.origin !== base.origin) {
+                    throw new Error(`connectPeer: ${url} advertises '${protocol}' at ${resolved.origin}, a different origin`);
+                }
+                return resolved.toString();
+            };
+            const peerEndpoint = resolveEndpoint(peerPath, PEER_PROTOCOL_NAME);
+            const syncEndpoint = resolveEndpoint(syncPath, SYNC_PROTOCOL_NAME);
+            const transport = new ClientTransport({
+                url: peerEndpoint,
+                fetch: deps.runtime.fetch
+            });
+            const client = new Client({
+                runtime: deps.runtime,
+                identity: deps.identity,
+                logger: deps.logger.getChild('peer-client'),
+                serverID: info.did,
+                transport
+            });
+            let result;
+            try {
+                result = await client.request('peer/groups', {
+                    param: {}
+                });
+            } catch (error) {
+                // Nothing has been stored yet — tear down the just-built connection so a
+                // failed connect leaves no live transport behind.
+                try {
+                    await client.dispose();
+                } catch  {
+                // best-effort
+                }
+                try {
+                    await transport.dispose();
+                } catch  {
+                // best-effort
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`connectPeer: peer/groups failed against ${peerEndpoint}: ${message}`, {
+                    cause: error
+                });
+            }
+            // The DID this connection is keyed on has to be the DID it addresses.
+            // `info.did` is what every request on this client is sent to — `serverID`
+            // becomes the `aud` claim — and it is also what `syncEndpoint` was
+            // resolved beside; `result.did` is a field the remote wrote into its own
+            // `peer/groups` body. Neither is authenticated on its own: `/info` is a
+            // plain fetch. What this refuses is the two disagreeing, which would key
+            // the registry — and every grant a caller names off it — on one identity
+            // while the traffic is addressed to another.
+            if (normalizeDID(result.did) !== normalizeDID(info.did)) {
+                try {
+                    await client.dispose();
+                } catch  {
+                // best-effort
+                }
+                try {
+                    await transport.dispose();
+                } catch  {
+                // best-effort
+                }
+                throw new Error(`connectPeer: ${url} answered peer/groups as ${result.did} but identifies as ${info.did}`);
+            }
+            // Hold the connection in memory keyed by the remote DID. A repeat connect
+            // to the same DID replaces this entry and disposes the prior transport.
+            await deps.peerConnections.set({
+                peerDID: result.did,
+                endpoint: url,
+                syncEndpoint,
+                client,
+                transport
+            });
+            return {
+                did: result.did,
+                endpoint: url,
+                groups: result.groups.map((group)=>({
+                        id: group.id,
+                        name: group.name
+                    }))
+            };
+        },
+        sharePeerGroup: async (params)=>{
+            const { peerDID, groupID: inputGroupID, name, sendModels, receiveActivate } = params;
+            // `groupID` XOR `name`: share an existing group or create a new one. Checked
+            // here rather than in the designation: the two-optional-argument shape is
+            // this mutation's own, and the designation takes one resolved target. It
+            // runs BEFORE the connection check, so a malformed call is refused for
+            // being malformed whether or not a connection is held.
+            if (inputGroupID == null === (name == null)) {
+                throw new GraphQLError('sharePeerGroup requires exactly one of groupID (share existing) or name (create new)');
+            }
+            // The held connection is required — never auto-dial. A caller must run
+            // `connectPeer` first; nothing here is persisted to re-establish it.
+            // Checked before ANY designation: this is the connected path, so a caller
+            // with no connection must fail having changed nothing.
+            const connection = deps.peerConnections.get(peerDID);
+            if (connection == null) {
+                throw new GraphQLError(`sharePeerGroup: no active connection to ${peerDID} — call connectPeer first`);
+            }
+            const groupCtx = createGroupContext(ctx, deps);
+            const p2pStore = await getP2PStore(deps.stores);
+            // 0. Pull the peer's join request FIRST and bind it to the DID about to be
+            // granted access, before a single row is written.
+            //
+            // The two identities are derived independently: the circle grant names
+            // `peerDID`, the MLS recipient comes from the KeyPackage credential inside
+            // `prep.joinRequest`. Uncompared, a peer receives the group's keys under
+            // credential Y while this device grants circle read access to whatever X
+            // it asked for — the split leaf/membership-row identity
+            // `groups/join-request-identity.ts` forbids. Explicit circle membership
+            // alone satisfies `circleAccessPredicate`, so X is a real grant to a
+            // principal that never joined.
+            //
+            // Ahead of the designation for the reason `admitJoinRequest` states: a
+            // designation minted for a DID the invite then refuses leaves a share
+            // circle and catalog behind for a member that never joins. Costs one
+            // wasted KeyPackage when re-run against a group the peer already belongs
+            // to; the peer mints those on demand.
+            const prep = await connection.client.request('group/prepare-join', {
+                param: {}
+            });
+            const credentialDID = resolveJoinRequestDID(prep.joinRequest);
+            if (normalizeDID(credentialDID) !== normalizeDID(peerDID)) {
+                throw new GraphQLError(`sharePeerGroup: the peer's join request binds ${credentialDID}, not ${peerDID}`);
+            }
+            // Steps 1-4: designate the peer's access — the state the invite below
+            // snapshots. Deliberately not inlined here: any other way of admitting
+            // this peer must seed it identically.
+            const designated = await designatePeerAccess(deps, {
+                groupCtx,
+                selfDID: ctx.viewerDID,
+                peerDID,
+                target: name != null ? {
+                    name
+                } : {
+                    groupID: inputGroupID
+                },
+                operation: {
+                    name: 'sharePeerGroup',
+                    adminAction: 'share a group'
+                },
+                sendModels: sendModels ?? null,
+                receiveActivate,
+                setReadDefaultForCircle: params.setReadDefaultForCircle
+            });
+            const groupID = designated.group.id;
+            // 5. Two-phase MLS dance over the peer connection — skip entirely when the
+            // peer is already a group member (a retry after the dance completed). The
+            // lookup keys on the DID the credential above was bound to, so it can no
+            // longer miss on a peer that is in fact a member and re-run the dance.
+            const alreadyMember = await p2pStore.getGroupMember(groupID, peerDID);
+            if (alreadyMember == null) {
+                const inviteResult = await groupCtx.requestInvite({
+                    groupID,
+                    joinRequest: prep.joinRequest
+                });
+                if (inviteResult.invitePayload == null) {
+                    // The Add commit is still parked (this device's hub is offline): there
+                    // is no Welcome to complete the join with. Surface the pending state
+                    // rather than handing a null payload to `group/complete-join`.
+                    throw new GraphQLError(`sharePeerGroup: the invite commit is still pending (${inviteResult.request.status}) — retry once the hub is reachable`);
+                }
+                await connection.client.request('group/complete-join', {
+                    param: {
+                        invitePayload: inviteResult.invitePayload
+                    }
+                });
+            }
+            // 6. Register the sync peer (upsert on peer_did). No initial sync — the
+            // sharer pulls via `syncPeer` once catalogs are active.
+            await deps.syncManager.addPeer({
+                config: {
+                    peerDID,
+                    endpoint: connection.syncEndpoint
+                },
+                stores: deps.stores
+            });
+            return designated;
+        },
+        admitJoinRequest: async (params)=>{
+            const { groupID, joinRequest, sendModels, receiveActivate } = params;
+            // Resolve the joiner BEFORE anything is written. A designation minted for a
+            // DID the invite then refuses would leave a share circle and a catalog
+            // behind for a member that never joins.
+            const peerDID = resolveJoinRequestDID(joinRequest);
+            // Ahead of the roster read below, not only ahead of the writes. The
+            // designation runs this same gate, so reaching it at all is already
+            // admin-only — but the roster read answers "is this DID in the group",
+            // and a non-admin holding any join request could otherwise ask that
+            // question and read the answer off which refusal came back.
+            await requireGroupAdmin({
+                store: await getP2PStore(deps.stores),
+                groupID,
+                did: ctx.viewerDID,
+                action: 'admit a member to the group'
+            });
+            // Where `serveGroupInvite` EVICTS a stale leaf for a DID already in the
+            // roster and re-adds it, this refuses. That eviction is justified there by
+            // the peer handler having signature-verified the caller; nothing verifies
+            // this request's author, so honouring the same branch would let a payload
+            // an attacker got in front of an admin remove a current member from the
+            // group — a denial of service authored by the admin who pasted it.
+            const existingLeafIndex = await deps.registry.readHandle(groupID, (handle)=>handle.findMemberLeafIndex(peerDID), {
+                stores: deps.stores
+            });
+            if (existingLeafIndex != null) {
+                throw new GraphQLError(`admitJoinRequest: ${peerDID} is already a member of group ${groupID} — refused rather than re-added, because nothing here verifies who authored the join request`);
+            }
+            const groupCtx = createGroupContext(ctx, deps);
+            // The same designation `sharePeerGroup` performs, on the same function, so
+            // an admitted peer is seeded identically whether or not a connection exists.
+            const designated = await designatePeerAccess(deps, {
+                groupCtx,
+                selfDID: ctx.viewerDID,
+                peerDID,
+                target: {
+                    groupID
+                },
+                operation: {
+                    name: 'admitJoinRequest',
+                    adminAction: 'admit a member to the group'
+                },
+                sendModels: sendModels ?? null,
+                receiveActivate,
+                setReadDefaultForCircle: params.setReadDefaultForCircle
+            });
+            // Minted last, through the same request facade: the invite payload
+            // snapshots exactly what the designation above wrote.
+            const inviteResult = await groupCtx.requestInvite({
+                groupID: designated.group.id,
+                joinRequest
+            });
+            if (inviteResult.invitePayload == null) {
+                // The Add commit is still parked, so there is no Welcome to hand back.
+                // Surface the pending state rather than returning a null payload the
+                // operator would carry to a joiner that cannot use it.
+                throw new GraphQLError(`admitJoinRequest: the invite commit is still pending (${inviteResult.request.status}) — retry once this device's commit lane is reachable`);
+            }
+            return {
+                ...designated,
+                peerDID,
+                invitePayload: inviteResult.invitePayload
+            };
+        },
+        joinPeerGroup: async (params)=>{
+            const { peerDID, groupID } = params;
+            // The held connection is required — never auto-dial. A caller must run
+            // `connectPeer` first (and discover the group from its group list).
+            const connection = deps.peerConnections.get(peerDID);
+            if (connection == null) {
+                throw new GraphQLError(`joinPeerGroup: no active connection to ${peerDID} — call connectPeer first`);
+            }
+            const selfDID = ctx.viewerDID;
+            const [p2pStore, graphStore] = await Promise.all([
+                getP2PStore(deps.stores),
+                getGraphStore(deps.stores)
+            ]);
+            // 1. Inbound MLS dance — skipped only when THIS device holds the full
+            // local group state (MLS state + own membership row): a retry after a
+            // prior completed join. A membership row WITHOUT MLS state means the
+            // device lost its state mid-dance; re-running the dance lets the inviter
+            // evict the stale roster entry and re-add with a fresh Welcome.
+            // `prepareRequest` mints + stashes the KeyPackage under `selfDID`; the
+            // remote `group/invite` returns the Welcome + seeds; `complete` joins MLS
+            // and folds the seeded control state (ledger/circles/access-defaults/
+            // catalogs) so circles project — and catalogs arrive KNOWN — at join.
+            const membershipRow = await p2pStore.getGroupMember(groupID, selfDID);
+            const mlsState = await deps.groupManager.loadGroup(deps.stores, groupID);
+            const alreadyJoined = membershipRow != null && mlsState != null;
+            if (!alreadyJoined) {
+                const joinCtx = createJoinContext(ctx, deps);
+                const prep = await joinCtx.prepareRequest();
+                const invite = await connection.client.request('group/invite', {
+                    param: {
+                        groupID,
+                        joinRequest: prep.joinRequest
+                    }
+                });
+                await joinCtx.complete(invite.invitePayload);
+            }
+            // 2. Register the sync peer (upsert on peer_did). No access writes, no
+            // activation, no initial sync — the user opts into what to send/receive
+            // afterward via the explicit surfaces (`setModelAccessDefaults` /
+            // `activateCatalogSync`), and `syncPeer` pulls only active-catalog scopes.
+            await deps.syncManager.addPeer({
+                config: {
+                    peerDID,
+                    endpoint: connection.syncEndpoint
+                },
+                stores: deps.stores
+            });
+            // 3. Ledger-catchup backstop: fold any entries appended after the invite
+            // snapshot was minted (also covers a member that missed broadcasts). MUST
+            // pass `quorum` — without it the gather blocks the full default window.
+            // Non-fatal: a backstop, not the primary seeding.
+            try {
+                await deps.requestLedgerCatchup(groupID, {
+                    quorum: 1,
+                    timeoutMs: 2000
+                });
+            } catch (error) {
+                deps.logger.warn('joinPeerGroup: ledger catch-up failed (non-fatal)', {
+                    groupID,
+                    error
+                });
+            }
+            // 4. Report the group's known catalogs (its circles' catalog IDs present
+            // locally) so the app can render the receive side of the share settings.
+            // Seeded known; the user activates later via `activateCatalogSync`. This
+            // leg runs OUTSIDE the alreadyJoined short-circuit and only reads, so a
+            // retry — including the alreadyJoined path — recomputes the same payload.
+            const circles = await p2pStore.listCirclesByGroup(groupID);
+            // The known-catalog scan and the open-circle `pulling` computation read the
+            // same catalog rows, so fetch every one the group's circles name in a
+            // single query and serve both from it.
+            const catalogs = createCatalogLoader(graphStore);
+            await catalogs.prime(circles.flatMap((circle)=>circle.catalog_ids));
+            const loadCatalog = catalogs.load;
+            const seenCatalogIDs = new Set();
+            const knownCatalogIDs = [];
+            for (const circle of circles){
+                for (const catalogID of circle.catalog_ids){
+                    if (seenCatalogIDs.has(catalogID)) continue;
+                    seenCatalogIDs.add(catalogID);
+                    if (await loadCatalog(catalogID) != null) {
+                        knownCatalogIDs.push(catalogID);
+                    }
+                }
+            }
+            // 5. Open-circle picker: the group's OPEN circles, each carrying THIS
+            // device's current pull/share state — computed from local state alone,
+            // with no member-authored wire entry and no extra network round-trip.
+            // `pulling` is true only when the circle has catalogs and every one is
+            // active locally: the exact post-state a pull that activates all the
+            // circle's catalogs together leaves behind (a pull-off deactivating them
+            // all inverts it), so it round-trips with the pull toggle; a zero-catalog
+            // circle has nothing to pull and is false. `sharing` lists the models this
+            // device lets the circle read — its OWN read access-default rows naming the
+            // circle (write defaults are excluded, matching how the share toggle writes
+            // read defaults). Closed circles are omitted: belonging to one is a grant,
+            // not a user opt-in.
+            const ownDefaults = await graphStore.listUserModelAccessDefaults(selfDID);
+            const openCircles = [];
+            for (const circle of circles){
+                if (circle.open !== 1) continue;
+                openCircles.push(await circleSyncState(circle, ownDefaults, loadCatalog));
+            }
+            const groupRow = await p2pStore.getGroup(groupID);
+            if (groupRow == null) {
+                throw new GraphQLError(`joinPeerGroup: group ${groupID} not found after join`);
+            }
+            const group = {
+                id: groupRow.id,
+                name: groupRow.name,
+                description: groupRow.description,
+                createdBy: groupRow.created_by,
+                createdAt: toISO(groupRow.created_at)
+            };
+            return {
+                group,
+                knownCatalogIDs,
+                alreadyJoined,
+                openCircles
+            };
+        },
+        setCircleSync: async (params)=>{
+            const { circleID, pull, share } = params;
+            const selfDID = ctx.viewerDID;
+            const [p2pStore, graphStore] = await Promise.all([
+                getP2PStore(deps.stores),
+                getGraphStore(deps.stores)
+            ]);
+            // Access gate — runs BEFORE pull and BEFORE share, so a rejected call
+            // writes nothing and activates nothing (fail-closed, matching
+            // sharePeerGroup's guard). `getCircle` excludes removed rows, so an
+            // unknown OR tombstoned circle reads null here.
+            const circle = await p2pStore.getCircle(circleID);
+            if (circle == null) {
+                throw new GraphQLError(`setCircleSync: circle ${circleID} not found or removed`);
+            }
+            // Membership per this device's own view (open circles count a group member
+            // as a member); an unreachable circle is rejected before any write.
+            if (!await p2pStore.isMemberOfAnyCircle(selfDID, [
+                circleID
+            ])) {
+                throw new GraphQLError(`setCircleSync: ${selfDID} cannot access circle ${circleID} — not a member`);
+            }
+            const groupID = circle.group_id;
+            // Ordering: local pull first, then the share rows, then the push. A crash
+            // after pull, before share, leaves pull active and share unwritten; a retry
+            // re-activates (flag no-op) and re-writes the share (LWW by HLC). Re-applying
+            // the identical end state is a no-op: the diff is empty and the flags match.
+            // 1. pull — purely local catalog activation. No entry, no broadcast, no push.
+            // The circle's catalogs flip together, so one statement covers them.
+            if (pull != null) {
+                await graphStore.setCatalogsActive(circle.catalog_ids, pull);
+            }
+            // 2. share — an END-STATE diff over the caller's OWN read defaults naming
+            // the circle. Every write is owner-signed (owner == caller) through the
+            // executors, so it only ever touches the caller's rows.
+            const pushRows = [];
+            if (share != null) {
+                const ownDefaults = await graphStore.listUserModelAccessDefaults(selfDID);
+                const currentShared = new Set(circleSharing(ownDefaults, circleID));
+                const target = new Set(share.models);
+                // The rules the two arms read are already in `ownDefaults`; index it
+                // rather than re-reading each model. The arms are disjoint by
+                // construction (`target` vs `currentShared \ target`), so neither arm's
+                // writes stale the other's lookups.
+                const existingByKey = indexDefaults(ownDefaults);
+                // Add: a target model whose read rule does not yet name the circle.
+                for (const modelID of target){
+                    if (currentShared.has(modelID)) {
+                        continue;
+                    }
+                    const existing = existingByKey.get(`${modelID}:read`);
+                    if (existing == null) {
+                        // No read rule: write a fresh restricted rule naming only the circle.
+                        await params.setReadDefault({
+                            modelID,
+                            accessLevel: 'restricted',
+                            allowedDIDs: null,
+                            allowedCircles: [
+                                circleID
+                            ],
+                            allowedGroups: null
+                        });
+                    } else {
+                        // Union the circle into the existing rule, preserving any
+                        // allowedDIDs / allowedGroups / other circles. `only_owner` reads no
+                        // circle at all, so leaving the level would name the circle in a rule
+                        // that grants it nothing — the share would be reported and mean
+                        // nothing. Sharing IS the request to let the circle read, so the
+                        // level widens to `restricted`. `anyone` already grants the circle
+                        // read and is never narrowed.
+                        const nextCircles = Array.from(new Set([
+                            ...existing.allowedCircles ?? [],
+                            circleID
+                        ]));
+                        const accessLevel = existing.level === 'only_owner' ? 'restricted' : existing.level;
+                        await params.setReadDefault({
+                            modelID,
+                            accessLevel,
+                            allowedDIDs: existing.allowedDIDs,
+                            allowedCircles: nextCircles,
+                            allowedGroups: existing.allowedGroups
+                        });
+                        if (existing.level === 'only_owner') {
+                            deps.logger.warn('setCircleSync: model read default was only_owner; widened to restricted so the circle can read', {
+                                modelID,
+                                circleID
+                            });
+                        } else if (existing.level === 'anyone') {
+                            deps.logger.warn('setCircleSync: model read default already grants anyone; circle added, level not narrowed', {
+                                modelID,
+                                circleID
+                            });
+                        }
+                    }
+                }
+                // Remove: a model that currently names the circle but is not in target.
+                for (const modelID of currentShared){
+                    if (target.has(modelID)) {
+                        continue;
+                    }
+                    const existing = existingByKey.get(`${modelID}:read`);
+                    if (existing == null) {
+                        continue;
+                    }
+                    const nextCircles = (existing.allowedCircles ?? []).filter((c)=>c !== circleID);
+                    const noDIDs = (existing.allowedDIDs ?? []).length === 0;
+                    const noGroups = (existing.allowedGroups ?? []).length === 0;
+                    if (existing.level === 'restricted' && nextCircles.length === 0 && noDIDs && noGroups) {
+                        // A `restricted` rule with no circles/DIDs/groups grants NO ONE
+                        // (owner only). Remove it entirely so the model returns to the SERVER
+                        // default rather than being pinned owner-only under a future default
+                        // change — the faithful "stop sharing entirely". Fires
+                        // `access-default:remove`. The restriction to the `restricted` level
+                        // is deliberate: removing an emptied `only_owner` rule would WIDEN to
+                        // the server default, and removing an `anyone` rule would silently
+                        // narrow a global grant — neither is the caller's intent, so those
+                        // are rewritten with the circle dropped instead.
+                        await params.removeReadDefault(modelID);
+                    } else {
+                        await params.setReadDefault({
+                            modelID,
+                            accessLevel: existing.level,
+                            allowedDIDs: existing.allowedDIDs,
+                            allowedCircles: nextCircles.length > 0 ? nextCircles : null,
+                            allowedGroups: existing.allowedGroups
+                        });
+                    }
+                // Removals/tightenings are NOT pushed — they propagate via the
+                // `access-default:remove` / `:set` broadcasts (eventual). A brief
+                // over-serve by a peer is the same exposure as any circle close.
+                }
+                // Push rows are collected from the WHOLE target set, not just the models
+                // this call added: a previous attempt that committed the share rows and
+                // then failed on the push must re-push on retry, and that retry sees the
+                // models as already shared. Re-pushing a row a peer already holds is a
+                // no-op there (LWW by the row's own HLC).
+                // Re-read AFTER the writes above — these rows are their post-state, and
+                // the row carries its own anchor, so one list replaces a rule + HLC pair
+                // per model. Signing is CPU-bound and touches no store, so the tokens are
+                // minted concurrently.
+                const writtenByKey = indexDefaults(await graphStore.listUserModelAccessDefaults(selfDID));
+                const signed = await Promise.all(Array.from(target, async (modelID)=>{
+                    const written = writtenByKey.get(`${modelID}:read`);
+                    if (written?.hlc == null) {
+                        return null;
+                    }
+                    const hlc = written.hlc;
+                    const rule = {
+                        level: written.level,
+                        allowedDIDs: written.allowedDIDs,
+                        allowedCircles: written.allowedCircles,
+                        allowedGroups: written.allowedGroups
+                    };
+                    const auth = await signAccessDefaultSet(deps.identity, {
+                        modelID,
+                        permissionType: 'read',
+                        rule,
+                        hlc
+                    });
+                    return {
+                        ownerDID: selfDID,
+                        modelID,
+                        permissionType: 'read',
+                        rule,
+                        hlc,
+                        auth
+                    };
+                }));
+                pushRows.push(...signed.filter((row)=>row != null));
+            }
+            // 3. Push the shared models' read-default SET rows to the group's connected
+            // in-group peers so
+            // a counterparty can authorize the new pull without waiting on hub fan-out
+            // (which may be dropped for a group with no live binding). Push failure
+            // fails the mutation (unwrapped, per the end-state contract); the retry is
+            // idempotent. `servePushControl` has NO remove arm — a "stop sharing"
+            // tightening is broadcast-only (known gap), never pushed here.
+            // Distinct peers over the network with nothing shared between them, so the
+            // pushes run concurrently: sequentially, one slow peer delays every peer
+            // behind it. A failure still fails the mutation, but every peer is
+            // attempted first rather than the fan-out stopping at the first error —
+            // strictly closer to the end-state contract, since the retry is idempotent.
+            if (pushRows.length > 0) {
+                const connections = deps.peerConnections.list();
+                const inGroup = await Promise.all(connections.map((connection)=>p2pStore.isGroupMember(groupID, connection.peerDID)));
+                await Promise.all(connections.filter((_connection, index)=>inGroup[index]).map((connection)=>connection.client.request('group/push-control', {
+                        param: {
+                            groupID,
+                            accessDefaults: pushRows
+                        }
+                    })));
+            }
+            // Post-state through the shared builder, so what this mutation returns is
+            // exactly what a `circleSync` re-read (or the join-time picker) reports.
+            // The circle row is re-read: a concurrent settings apply may have flipped
+            // `open` while the share was being written.
+            const [reread, finalDefaults] = await Promise.all([
+                p2pStore.getCircle(circleID),
+                graphStore.listUserModelAccessDefaults(selfDID)
+            ]);
+            const finalCircle = reread ?? circle;
+            const catalogs = createCatalogLoader(graphStore);
+            await catalogs.prime(finalCircle.catalog_ids);
+            return await circleSyncState(finalCircle, finalDefaults, catalogs.load);
+        },
+        listCircleSyncStates: async (groupID)=>{
+            const selfDID = ctx.viewerDID;
+            const [p2pStore, graphStore] = await Promise.all([
+                getP2PStore(deps.stores),
+                getGraphStore(deps.stores)
+            ]);
+            // Only the circles this device can currently reach: an open circle it is a
+            // group member of, or one it holds an explicit grant for. A circle the admin
+            // closed since the join drops out here, which is how the app learns to stop
+            // offering it.
+            const [circles, reachable, ownDefaults] = await Promise.all([
+                p2pStore.listCirclesByGroup(groupID),
+                p2pStore.getCirclesForMember(selfDID),
+                graphStore.listUserModelAccessDefaults(selfDID)
+            ]);
+            const reachableIDs = new Set(reachable.map((circle)=>circle.id));
+            const visible = circles.filter((circle)=>reachableIDs.has(circle.id));
+            const catalogs = createCatalogLoader(graphStore);
+            await catalogs.prime(visible.flatMap((circle)=>circle.catalog_ids));
+            const states = [];
+            for (const circle of visible){
+                states.push(await circleSyncState(circle, ownDefaults, catalogs.load));
+            }
+            return states;
+        }
+    };
+}