@kubun/plugin-p2p 0.13.1 → 0.15.0

package/lib/peer/blob-fetch.d.ts

@@ -1,24 +1,8 @@
+import type { BlobAPI } from '@kubun/plugin-blob-api';
 import type { Fetch } from '@sozai/runtime';
 import type { BlobManifestResult } from '../protocol.js';
 import type { PeerConnection, PeerConnectionRegistry } from './connection-registry.js';
-export type BlobFetchAPI = {
-    getAttachment(attachmentID: string): Promise<{
-        state: string;
-    } | null>;
-    beginFetch(params: {
-        attachmentID: string;
-        chunkSize: number;
-        chunkDigests: Array<Uint8Array>;
-    }): Promise<void>;
-    getPresentChunks(attachmentID: string): Promise<Array<number>>;
-    stageChunk(params: {
-        attachmentID: string;
-        index: number;
-        offset: number;
-        bytes: Uint8Array;
-    }): Promise<void>;
-    completeFetch(attachmentID: string): Promise<void>;
-};
+export type BlobFetchAPI = Pick<BlobAPI, 'getAttachment' | 'beginFetch' | 'getPresentChunks' | 'stageChunk' | 'completeFetch'>;
 export type PeerConnectionLister = {
     list(): Array<PeerConnection>;
 };

package/lib/protocol.d.ts

@@ -229,6 +229,13 @@ export declare const syncProtocol: {
                     };
                     readonly description: "Signed subject states the caller holds, for updates and revocation GC";
                 };
+                readonly owners: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Owner DIDs to fetch the latest durable manifest for, addressed to the caller — the PULL repair channel independent of LIVE broadcast.";
+                };
             };
             readonly required: readonly ["held"];
             readonly additionalProperties: false;
@@ -327,6 +334,9 @@ export declare const syncProtocol: {
                                     readonly additionalProperties: false;
                                 };
                             };
+                            readonly grantorAuthority: {
+                                readonly type: "string";
+                            };
                         };
                         readonly required: readonly ["keyID", "keyVersion", "suite", "ownerDID", "keyOp", "keyBranches", "wrapping", "entries"];
                         readonly additionalProperties: false;
@@ -362,6 +372,26 @@ export declare const syncProtocol: {
                     };
                     readonly description: "Tombstones for advertised held IDs that are now revoked (GC)";
                 };
+                readonly manifests: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly manifest: {
+                                readonly type: "string";
+                            };
+                            readonly delegationTokens: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly required: readonly ["manifest", "delegationTokens"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly description: "The latest stored manifest addressed to the caller for each requested owner — the durable repair channel independent of LIVE broadcast.";
+                };
             };
             readonly required: readonly ["bundles", "tombstones"];
             readonly additionalProperties: false;

package/lib/protocol.js

@@ -290,6 +290,13 @@ export const syncProtocol = {
                         additionalProperties: false
                     },
                     description: 'Signed subject states the caller holds, for updates and revocation GC'
+                },
+                owners: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Owner DIDs to fetch the latest durable manifest for, addressed to the caller — the PULL repair channel independent of LIVE broadcast.'
                 }
             },
             required: [
@@ -406,6 +413,12 @@ export const syncProtocol = {
                                     ],
                                     additionalProperties: false
                                 }
+                            },
+                            // Persisted grantor-authority envelope for a delegate-signed
+                            // wrapping (absent for owner-signed); declared so it isn't an
+                            // `additionalProperties: false` violation if result validation is enabled.
+                            grantorAuthority: {
+                                type: 'string'
                             }
                         },
                         required: [
@@ -457,6 +470,29 @@ export const syncProtocol = {
                         additionalProperties: false
                     },
                     description: 'Tombstones for advertised held IDs that are now revoked (GC)'
+                },
+                manifests: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            manifest: {
+                                type: 'string'
+                            },
+                            delegationTokens: {
+                                type: 'array',
+                                items: {
+                                    type: 'string'
+                                }
+                            }
+                        },
+                        required: [
+                            'manifest',
+                            'delegationTokens'
+                        ],
+                        additionalProperties: false
+                    },
+                    description: 'The latest stored manifest addressed to the caller for each requested owner — the durable repair channel independent of LIVE broadcast.'
                 }
             },
             required: [

package/lib/schema.d.ts

@@ -1,5 +1,20 @@
 import type { SchemaExtension } from '@kubun/engine';
 import { type Logger } from '@kubun/logger';
+import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
 import { type P2PEventEmitter } from './groups/events.js';
 import type { SyncManager } from './sync/sync-manager.js';
-export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, syncManager: SyncManager, logger?: Logger): SchemaExtension;
+/**
+ * Recurring group catch-up control the GraphQL resolvers call, threaded from the
+ * plugin so they reach the same workflow-backed schedule the runtime API arms.
+ * Results are the workflow plugin's PeriodicSync projection (opaque here).
+ */
+export type GroupPeriodicSyncControl = {
+    enableGroupPeriodicSync(groupID: string, policy?: AdaptivePolicy): Promise<unknown>;
+    disableGroupPeriodicSync(groupID: string): Promise<unknown | null>;
+    getGroupPeriodicSync(groupID: string): Promise<unknown | null>;
+};
+/** Deploy-config the p2p schema extension reads. */
+export type P2PSchemaConfig = {
+    periodicSync?: boolean;
+};
+export declare function createP2PSchemaExtension(emitter: P2PEventEmitter, syncManager: SyncManager, logger?: Logger, control?: GroupPeriodicSyncControl, config?: P2PSchemaConfig): SchemaExtension;

package/lib/schema.js

@@ -581,6 +581,12 @@ extend type Query {
   one group. The store is per-device.
   """
   controlRequests(groupID: ID): [ControlRequest!]!
+  """
+  Prove this device holds the complete credential set the owner's manifests
+  promised it: the union of every per-grantor manifest's keys, minus those that
+  actually decrypt-verify here. An empty missing list means the pull is complete.
+  """
+  credentialProvisioningStatus(ownerDID: DID!): CredentialProvisioningStatus!
 }
 
 enum GroupHealthCondition {
@@ -644,6 +650,48 @@ type ControlRequest implements Node {
   settledAt: DateTimeISO
 }
 
+"""
+One key's outcome from a grantDeviceCredentials batch: what happened when this
+device tried to hand one of the owner's active credential keys to the recipient
+device. Never an error thrown out of the batch — every key reports its own fate.
+"""
+type CredentialGrantOutcome {
+  keyID: ID!
+  """
+  The key's version after this call, or null when nothing was granted
+  (not-held / error outcomes carry no version).
+  """
+  version: Int
+  outcome: String!
+  """Present on not-held and error; the caught error's message."""
+  reason: String
+}
+
+type GrantDeviceCredentialsPayload {
+  results: [CredentialGrantOutcome!]!
+  """A grantor-signed manifest claiming exactly the granted/refreshed keys above."""
+  manifest: String!
+  """The provisioning epoch this manifest was allocated under."""
+  epoch: Int!
+}
+
+"""
+Readiness of this device's credential provisioning for one owner. A key counts
+materialized only when its wrapping decrypt-verifies (or, for a zero-entry key,
+merely opens) — presence and a valid signature alone never suffice.
+"""
+type CredentialProvisioningStatus {
+  complete: Boolean!
+  """The expected keyIDs not yet materialized on this device."""
+  missing: [ID!]!
+  """
+  Why complete is false: not-initiated (no expectation on record yet),
+  pending (an attempt is in flight, its floor not yet bound), or incomplete
+  (asked for, not yet fully materialized/proven). Absent when complete.
+  """
+  reason: String
+}
+
 extend type Mutation {
   connectPeer(url: String!): ConnectPeerPayload!
   sharePeerGroup(peerDID: ID!, groupID: ID, name: String, send: ShareInput, receive: ShareReceiveInput): SharePeerGroupPayload!
@@ -654,7 +702,15 @@ extend type Mutation {
   DID comes from the request's KeyPackage credential; a disagreeing did field, or a
   DID already on the roster, is refused.
   """
-  admitJoinRequest(groupID: ID!, joinRequest: String!, send: ShareInput, receive: ShareReceiveInput): AdmitJoinRequestPayload!
+  admitJoinRequest(groupID: ID!, joinRequest: String!, grants: [String!], send: ShareInput, receive: ShareReceiveInput): AdmitJoinRequestPayload!
+  """
+  Grant a device recipientDID this device's active credential keys for ownerDID,
+  resolving the recipient from the group's MLS roster. Returns every key's
+  outcome plus a grantor-signed manifest the recipient checks its store against.
+  minEpoch floors the allocated epoch at the recipient's held epoch, so a
+  reprovision attempt always supersedes a manifest it already holds. Defaults to 0.
+  """
+  grantDeviceCredentials(groupID: ID!, recipientDID: DID!, ownerDID: DID!, minEpoch: Int): GrantDeviceCredentialsPayload!
   joinPeerGroup(peerDID: ID!, groupID: ID!): JoinPeerGroupPayload!
   """
   Apply one circle's desired sync end state. A null argument leaves that dimension
@@ -760,9 +816,30 @@ extend type Subscription {
   controlRequestSettled(groupID: ID, requestID: ID): ControlRequest!
 }
 `;
-export function createP2PSchemaExtension(emitter, syncManager, logger = getKubunLogger('p2p-schema')) {
+// Recurring-sync control fields, appended only when the deploy opted in. Gated
+// because they reference `PeriodicSync`, defined by the co-deployed workflow
+// plugin — referencing it on a p2p-only graph would fail schema build.
+const periodicSyncSDL = `
+extend type Query {
+  groupPeriodicSync(groupID: ID!): PeriodicSync
+}
+
+extend type Mutation {
+  enableGroupPeriodicSync(groupID: ID!, policy: JSON): PeriodicSync!
+  disableGroupPeriodicSync(groupID: ID!): PeriodicSync
+}
+`;
+export function createP2PSchemaExtension(emitter, syncManager, logger = getKubunLogger('p2p-schema'), control, config) {
+    const periodicSyncEnabled = config?.periodicSync === true && control != null;
+    const periodicSyncQueryFields = periodicSyncEnabled ? {
+        groupPeriodicSync: (_source, args, _context)=>control.getGroupPeriodicSync(args.groupID)
+    } : {};
+    const periodicSyncMutationFields = periodicSyncEnabled ? {
+        enableGroupPeriodicSync: (_source, args, _context)=>control.enableGroupPeriodicSync(args.groupID, args.policy),
+        disableGroupPeriodicSync: (_source, args, _context)=>control.disableGroupPeriodicSync(args.groupID)
+    } : {};
     return {
-        sdl,
+        sdl: periodicSyncEnabled ? sdl + periodicSyncSDL : sdl,
         // These mutations perform network I/O (peer discovery, the MLS dance,
         // merkle sync) and/or apply received mutations in their own per-step
         // transactions. Running them inside `mutateGraph`'s write transaction would
@@ -789,10 +866,20 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
             // Waits for its Add commit to land. The lane reads the group's handle on
             // the registry's own connection, so holding a write transaction across
             // that wait deadlocks single-connection SQLite.
-            'requestInviteToGroup'
+            'requestInviteToGroup',
+            // Write the workflow store synchronously and must return the resulting
+            // projection; running them inside `mutateGraph`'s write transaction would
+            // hold the single-connection DB across the workflow-store write and
+            // deadlock (as the connector's enable/disable are declared for the same
+            // reason).
+            ...periodicSyncEnabled ? [
+                'enableGroupPeriodicSync',
+                'disableGroupPeriodicSync'
+            ] : []
         ],
         resolvers: {
             queryFields: {
+                ...periodicSyncQueryFields,
                 groups: async (_source, _args, context)=>{
                     return await requireP2P(context).group.list();
                 },
@@ -849,6 +936,11 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                     const requests = await requireP2P(context).group.listControlRequests(args.groupID);
                     return requests.map(toControlRequestSDL);
                 },
+                credentialProvisioningStatus: async (_source, args, context)=>{
+                    return await requireP2P(context).peer.credentialProvisioningStatus({
+                        ownerDID: args.ownerDID
+                    });
+                },
                 ownDelegationTokens: async (_source, args, context)=>{
                     const viewerDID = context.getViewer();
                     if (viewerDID == null || context.p2p == null) {
@@ -875,6 +967,7 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                 }
             },
             mutationFields: {
+                ...periodicSyncMutationFields,
                 connectPeer: async (_source, args, context)=>{
                     const peer = await requireP2P(context).peer.connect(args.url);
                     return {
@@ -916,6 +1009,7 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                     return await requireP2P(context).peer.admitJoinRequest({
                         groupID: args.groupID,
                         joinRequest: args.joinRequest,
+                        grants: args.grants ?? undefined,
                         sendModels: send?.models ?? null,
                         receiveActivate: receive?.activate ?? false,
                         // Same owner-signed executor `sharePeerGroup` binds, so the rows this
@@ -934,6 +1028,21 @@ export function createP2PSchemaExtension(emitter, syncManager, logger = getKubun
                         }
                     });
                 },
+                grantDeviceCredentials: async (_source, args, context)=>{
+                    const { results, manifest, epoch } = await requireP2P(context).peer.grantDeviceCredentials({
+                        groupID: args.groupID,
+                        recipientDID: args.recipientDID,
+                        ownerDID: args.ownerDID,
+                        ...args.minEpoch == null ? {} : {
+                            minEpoch: args.minEpoch
+                        }
+                    });
+                    return {
+                        results,
+                        manifest,
+                        epoch
+                    };
+                },
                 joinPeerGroup: async (_source, args, context)=>{
                     return await requireP2P(context).peer.joinPeerGroup({
                         peerDID: args.peerDID,

package/lib/sync/group-sync-workflow.d.ts

@@ -0,0 +1,77 @@
+import type { Logger } from '@kubun/logger';
+import type { AdaptivePolicy, WorkflowOutcome } from '@kubun/plugin-workflow-api';
+import type { P2PEventEmitter } from '../groups/events.js';
+import type { PeerCatchUpData } from '../types.js';
+/** Queue lane (and workflow name) for group catch-up sync. */
+export declare const GROUP_SYNC_WORKFLOW = "group-sync";
+/** How many group catch-up passes may run at once on this peer. */
+export declare const GROUP_SYNC_CONCURRENCY = 4;
+type HandlerContext = {
+    state: Record<string, unknown>;
+    params?: unknown;
+    signal?: AbortSignal;
+};
+type HandlerResult = {
+    status: 'end';
+    state: Record<string, unknown>;
+    outcome?: WorkflowOutcome;
+};
+type GroupSyncHandler = (ctx: HandlerContext) => Promise<HandlerResult>;
+export type GroupSyncWorkflowDefinition = {
+    name: string;
+    initialAction: {
+        name: string;
+    };
+    handlers: Record<string, GroupSyncHandler>;
+};
+/**
+ * Map one catch-up pass to the outcome that paces the next run. A reachable peer
+ * that shipped mutations is productive (`changed`); a reachable peer with nothing
+ * new, or no scope to pull, is `idle`; no peer answered (none known, or none on)
+ * is `offline` so the scheduler backs off. A thrown apply never reaches here —
+ * the engine forces `error` on the failed terminal.
+ */
+export declare function classifyCatchUp(data: PeerCatchUpData): WorkflowOutcome;
+export type GroupSyncWorkflowParams = {
+    catchUpWithBestPeer: (groupID: string) => Promise<PeerCatchUpData>;
+    logger: Logger;
+};
+/**
+ * Build the `group-sync` workflow definition. The single `start` handler runs one
+ * `catchUpWithBestPeer` pass and classifies its result; a genuine throw is left to
+ * propagate so the engine forces the terminal `error` (and its backoff), never
+ * swallowed into a false success.
+ */
+export declare function createGroupSyncWorkflow(params: GroupSyncWorkflowParams): {
+    definition: GroupSyncWorkflowDefinition;
+};
+export type PeriodicSyncArmingAPI = {
+    scheduleAdaptive(name: string, params: unknown, opts: {
+        policy: AdaptivePolicy;
+        subjectKey: string;
+    }): Promise<{
+        id: string;
+    }>;
+    getPeriodicSync(scheduleID: string): Promise<unknown | null>;
+};
+/**
+ * Arm a group's recurring catch-up the first time it is joined — INSERT-IF-ABSENT.
+ * `scheduleAdaptive` is insert-OR-reactivate, so guarding on the existing
+ * projection is what stops a re-join or reboot resurrecting a schedule the user
+ * explicitly disabled. Deliberately the opposite of the explicit enable, which
+ * always (re)activates.
+ */
+export declare function armGroupPeriodicSyncIfAbsent(api: PeriodicSyncArmingAPI, groupID: string, policy: AdaptivePolicy): Promise<void>;
+/**
+ * Subscribe implicit arming to `groupJoined`. The listener is fire-and-forget and
+ * never throws into the emitter (`emit` rethrows listener failures, and this rides
+ * the group-create/join commit): its async work is detached and its failure logged.
+ * Returns the unsubscribe.
+ */
+export declare function wireGroupPeriodicSyncArming(params: {
+    emitter: P2PEventEmitter;
+    getWorkflowAPI: () => Promise<PeriodicSyncArmingAPI | undefined>;
+    policy: AdaptivePolicy;
+    logger: Logger;
+}): () => void;
+export {};

package/lib/sync/group-sync-workflow.js

@@ -0,0 +1,96 @@
+/** Queue lane (and workflow name) for group catch-up sync. */ export const GROUP_SYNC_WORKFLOW = 'group-sync';
+/** How many group catch-up passes may run at once on this peer. */ export const GROUP_SYNC_CONCURRENCY = 4;
+/**
+ * Map one catch-up pass to the outcome that paces the next run. A reachable peer
+ * that shipped mutations is productive (`changed`); a reachable peer with nothing
+ * new, or no scope to pull, is `idle`; no peer answered (none known, or none on)
+ * is `offline` so the scheduler backs off. A thrown apply never reaches here —
+ * the engine forces `error` on the failed terminal.
+ */ export function classifyCatchUp(data) {
+    switch(data.outcome){
+        case 'synced':
+            return data.messagesReceived > 0 ? 'changed' : 'idle';
+        case 'no-scopes':
+            return 'idle';
+        case 'no-candidates':
+        case 'no-route':
+            return 'offline';
+    }
+}
+/**
+ * Build the `group-sync` workflow definition. The single `start` handler runs one
+ * `catchUpWithBestPeer` pass and classifies its result; a genuine throw is left to
+ * propagate so the engine forces the terminal `error` (and its backoff), never
+ * swallowed into a false success.
+ */ export function createGroupSyncWorkflow(params) {
+    const { catchUpWithBestPeer, logger } = params;
+    const start = async (ctx)=>{
+        const { groupID } = ctx.params;
+        const data = await catchUpWithBestPeer(groupID);
+        const outcome = classifyCatchUp(data);
+        logger.debug('group catch-up classified', {
+            groupID,
+            outcome,
+            peerDID: data.peerDID
+        });
+        return {
+            status: 'end',
+            state: {
+                groupID
+            },
+            outcome
+        };
+    };
+    return {
+        definition: {
+            name: GROUP_SYNC_WORKFLOW,
+            initialAction: {
+                name: 'start'
+            },
+            handlers: {
+                start
+            }
+        }
+    };
+}
+/**
+ * Arm a group's recurring catch-up the first time it is joined — INSERT-IF-ABSENT.
+ * `scheduleAdaptive` is insert-OR-reactivate, so guarding on the existing
+ * projection is what stops a re-join or reboot resurrecting a schedule the user
+ * explicitly disabled. Deliberately the opposite of the explicit enable, which
+ * always (re)activates.
+ */ export async function armGroupPeriodicSyncIfAbsent(api, groupID, policy) {
+    const id = `${GROUP_SYNC_WORKFLOW}:${groupID}`;
+    if (await api.getPeriodicSync(id) == null) {
+        await api.scheduleAdaptive(GROUP_SYNC_WORKFLOW, {
+            groupID
+        }, {
+            policy,
+            subjectKey: groupID
+        });
+    }
+}
+/**
+ * Subscribe implicit arming to `groupJoined`. The listener is fire-and-forget and
+ * never throws into the emitter (`emit` rethrows listener failures, and this rides
+ * the group-create/join commit): its async work is detached and its failure logged.
+ * Returns the unsubscribe.
+ */ export function wireGroupPeriodicSyncArming(params) {
+    const { emitter, getWorkflowAPI, policy, logger } = params;
+    return emitter.on('groupJoined', (groupData)=>{
+        void (async ()=>{
+            try {
+                const api = await getWorkflowAPI();
+                if (api == null) {
+                    return;
+                }
+                await armGroupPeriodicSyncIfAbsent(api, groupData.id, policy);
+            } catch (error) {
+                logger.error('implicit group periodic-sync arm failed', {
+                    groupID: groupData.id,
+                    error
+                });
+            }
+        })();
+    });
+}

package/lib/sync/handlers.js

@@ -283,14 +283,33 @@ export { checkSyncDelegation };
                     ...toWireOp(op),
                     subjectID: op.subject_id
                 }));
+            // Durable PULL repair, independent of live broadcast: manifests addressed
+            // to the authenticated `callerDID`, never an owner-supplied recipient,
+            // so a manifest never leaks to a device other than the one it names.
+            let manifests;
+            if (ctx.param.owners != null && ctx.param.owners.length > 0) {
+                // Independent per-owner lookups — query concurrently, preserve owner order.
+                const perOwner = await Promise.all(ctx.param.owners.map((owner)=>store.listManifests({
+                        ownerDID: owner,
+                        recipientDID: callerDID
+                    })));
+                manifests = perOwner.flatMap((rows)=>rows.map((row)=>({
+                            manifest: row.token,
+                            delegationTokens: row.delegationTokens
+                        })));
+            }
             logger.debug('sync/reconcile-credentials served', {
                 callerDID,
                 bundles: bundles.length,
-                tombstones: tombstones.length
+                tombstones: tombstones.length,
+                manifests: manifests?.length ?? 0
             });
             return {
                 bundles,
-                tombstones
+                tombstones,
+                ...manifests != null && {
+                    manifests
+                }
             };
         }
     });

package/lib/sync/held-delegations.d.ts

@@ -0,0 +1,14 @@
+import type { StoreProvider } from '@kubun/db';
+/**
+ * The device's own held read delegations for a set of scope owners, as the JWT
+ * strings an outbound catch-up rides in `delegationTokens`.
+ *
+ * Each token is a capability the owner (grantor) issued to this device
+ * (audience); presenting it lets the peer's `checkSyncDelegation` arm of
+ * `authorizeScope` authorize a pull of that owner's documents — e.g. a paired
+ * device reading a controller's documents via the pairing-time delegation.
+ *
+ * Keyed `grantor: ownerDID, audience: selfDID` (the direction the gate checks).
+ * Owners equal to `selfDID` are skipped; results are de-duplicated.
+ */
+export declare function resolveHeldDelegationTokens(stores: StoreProvider, selfDID: string, owners: Iterable<string>): Promise<Array<string>>;

package/lib/sync/held-delegations.js

@@ -0,0 +1,34 @@
+import { DELEGATION_STORE, getDelegationStore } from '@kubun/store-delegation';
+/**
+ * The device's own held read delegations for a set of scope owners, as the JWT
+ * strings an outbound catch-up rides in `delegationTokens`.
+ *
+ * Each token is a capability the owner (grantor) issued to this device
+ * (audience); presenting it lets the peer's `checkSyncDelegation` arm of
+ * `authorizeScope` authorize a pull of that owner's documents — e.g. a paired
+ * device reading a controller's documents via the pairing-time delegation.
+ *
+ * Keyed `grantor: ownerDID, audience: selfDID` (the direction the gate checks).
+ * Owners equal to `selfDID` are skipped; results are de-duplicated.
+ */ export async function resolveHeldDelegationTokens(stores, selfDID, owners) {
+    const distinctOwners = new Set();
+    for (const owner of owners){
+        if (owner !== selfDID) {
+            distinctOwners.add(owner);
+        }
+    }
+    if (distinctOwners.size === 0 || !stores.hasStore(DELEGATION_STORE)) {
+        return [];
+    }
+    const delegationStore = await getDelegationStore(stores);
+    // Independent per-owner lookups — query concurrently; the Set dedups regardless of order.
+    const perOwner = await Promise.all([
+        ...distinctOwners
+    ].map((ownerDID)=>delegationStore.getDelegationTokens({
+            grantor: ownerDID,
+            audience: selfDID
+        })));
+    return [
+        ...new Set(perOwner.flat().map((row)=>row.token))
+    ];
+}