@bsv/sdk 2.1.1 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/identity/ContactsManager.ts

@@ -34,38 +34,74 @@ export class ContactsManager {
   private readonly CONTACTS_CACHE_KEY = 'metanet-contacts'
   private readonly originator?: string
 
+  // Performance state — prevents thundering herd of concurrent contact loads and
+  // short-circuits the overlay path entirely when we've previously observed an
+  // empty contacts basket. Both are invalidated by saveContact/removeContact and
+  // by an explicit forceRefresh.
+  private inFlightLoad: Promise<Contact[]> | null = null
+  private knownEmpty = false
+
   constructor (wallet?: WalletInterface, originator?: string) {
     this.wallet = wallet ?? new WalletClient()
     this.originator = originator
   }
 
   /**
-   * Load all records from the contacts basket
+   * Load all records from the contacts basket.
+   *
+   * Concurrent calls share a single in-flight load (no thundering herd). After
+   * the basket has been observed empty once, subsequent calls return `[]`
+   * synchronously without hitting the wallet — until `forceRefresh` is passed
+   * or a contact is saved/removed.
+   *
    * @param identityKey Optional specific identity key to fetch
    * @param forceRefresh Whether to force a check for new contact data
    * @param limit Maximum number of contacts to return
-   * @returns A promise that resolves with an array of contacts
    */
   async getContacts (identityKey?: PubKeyHex, forceRefresh = false, limit = 1000): Promise<Contact[]> {
+    if (forceRefresh) this.invalidate()
+
+    if (this.knownEmpty) return []
+
     if (!forceRefresh) {
       const fromCache = this.loadCachedContacts(identityKey)
       if (fromCache !== null) return fromCache
     }
 
-    const tags = await this.buildIdentityKeyTags(identityKey)
+    // Coalesce concurrent loads onto a single Promise so a fan-out of N
+    // identity calls produces ONE listOutputs + decrypt batch, not N.
+    this.inFlightLoad ??= this.loadContactsFromWallet(limit).finally(() => {
+      this.inFlightLoad = null
+    })
+    const all = await this.inFlightLoad
+    return identityKey == null ? all : all.filter(c => c.identityKey === identityKey)
+  }
+
+  /** Reset cached state. Call after writes. */
+  private invalidate (): void {
+    this.cache.removeItem(this.CONTACTS_CACHE_KEY)
+    this.knownEmpty = false
+    this.inFlightLoad = null
+  }
+
+  /** Underlying wallet load — invoked at most once concurrently via `inFlightLoad`. */
+  private async loadContactsFromWallet (limit: number): Promise<Contact[]> {
+    // Always load the full basket so subsequent filters (by identityKey) hit cache.
+    // Tag filtering is reserved for explicit per-key write paths.
     const outputs = await this.wallet.listOutputs(
-      { basket: 'contacts', include: 'locking scripts', includeCustomInstructions: true, tags, limit },
+      { basket: 'contacts', include: 'locking scripts', includeCustomInstructions: true, tags: [], limit },
       this.originator
     )
 
     if (outputs.outputs == null || outputs.outputs.length === 0) {
       this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify([]))
+      this.knownEmpty = true
       return []
     }
 
     const contacts = await this.decryptContactOutputs(outputs.outputs)
     this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
-    return identityKey != null ? contacts.filter(c => c.identityKey === identityKey) : contacts
+    return contacts
   }
 
   /** Returns cached contacts (optionally filtered) or null if cache is missing/invalid. */
@@ -158,6 +194,8 @@ export class ContactsManager {
       await this.createContactOutput(lockingScript, keyID, hashedIdentityKey, contact)
     }
     this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
+    this.knownEmpty = false
+    this.inFlightLoad = null
   }
 
   /** Computes the HMAC-based hash of an identity key for tag indexing. */
@@ -265,11 +303,14 @@ export class ContactsManager {
     if (cached != null && cached !== '') {
       try {
         const contacts: Contact[] = JSON.parse(cached)
-        this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts.filter(c => c.identityKey !== identityKey)))
+        const remaining = contacts.filter(c => c.identityKey !== identityKey)
+        this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(remaining))
+        this.knownEmpty = remaining.length === 0
       } catch (e) {
         console.warn('Failed to update cache after contact removal:', e)
       }
     }
+    this.inFlightLoad = null
 
     const tags = await this.buildIdentityKeyTags(identityKey)
     const outputs = await this.wallet.listOutputs(

package/src/identity/IdentityClient.ts

@@ -18,30 +18,74 @@ import { PrivateKey, Utils } from '../primitives/index.js'
 import { LookupResolver, SHIPBroadcaster, TopicBroadcaster, withDoubleSpendRetry } from '../overlay-tools/index.js'
 import { ContactsManager, Contact } from './ContactsManager.js'
 
+/**
+ * Maximum number of identity certificates to parse synchronously before yielding to the
+ * event loop. Keeps the main thread responsive when an overlay query returns many results
+ * (e.g. a bulk enrichment of N identityKeys).
+ */
+const PARSE_BATCH_SIZE = 32
+
+/**
+ * Yield control to the event loop so queued microtasks / timers can run. Uses
+ * `scheduler.yield()` when available (Chromium) or a 0ms macrotask fallback.
+ */
+async function yieldToEventLoop (): Promise<void> {
+  const sched = (globalThis as any).scheduler
+  if (sched != null && typeof sched.yield === 'function') {
+    return await sched.yield()
+  }
+  return await new Promise<void>((resolve) => setTimeout(resolve, 0))
+}
+
 /** Options for {@link IdentityClient.resolveByIdentityKey}. */
 export interface ResolveByIdentityKeyOptions {
-  /** Default `true`. If `false`, contacts are skipped and the overlay is queried directly. */
+  /**
+   * Opt-in to consulting personal contacts before/alongside the overlay. Default `false`.
+   *
+   * Most callers (including any client without a populated contacts basket) pay no benefit
+   * from the contacts path and incur its setup cost. Set `true` only in UI contexts where
+   * the user has likely saved contacts and a local cache hit is preferable to a fresh overlay
+   * answer.
+   */
+  useContacts?: boolean
+  /**
+   * Legacy alias for {@link useContacts}. When provided, takes precedence over the new flag.
+   * Kept for binary compatibility — new code should use `useContacts`.
+   */
   overrideWithContacts?: boolean
   /**
-   * Default `false`. When `true`, fire contacts and overlay in parallel (legacy behavior) instead
-   * of short-circuiting on a contacts hit. Use when callers specifically need a fresh overlay
-   * answer alongside the contact record.
+   * When `true` (and {@link useContacts} is also true), fire contacts and overlay in parallel
+   * rather than short-circuiting on a contacts hit. Use only when callers specifically need a
+   * fresh overlay answer alongside any cached contact record.
    */
   parallel?: boolean
 }
 
 /** Options for {@link IdentityClient.resolveByAttributes}. */
 export interface ResolveByAttributesOptions {
-  /** Default `true`. If `false`, contacts are skipped and the overlay is queried directly. */
+  /**
+   * Opt-in to consulting personal contacts before/alongside the overlay. Default `false`.
+   * See {@link ResolveByIdentityKeyOptions.useContacts}.
+   */
+  useContacts?: boolean
+  /** Legacy alias for {@link useContacts}. Takes precedence when provided. */
   overrideWithContacts?: boolean
   /**
-   * Default `false`. When `true`, fire contacts and overlay in parallel (legacy behavior). The
-   * contacts-first path tries to match the supplied attributes against the locally-stored
-   * contacts; if any contact matches every attribute, the overlay is skipped.
+   * When `true` (and {@link useContacts} is also true), fire contacts and overlay in parallel.
    */
   parallel?: boolean
 }
 
+/** Normalize either legacy boolean / new options object into a canonical { useContacts, parallel }. */
+function normalizeOpts (
+  raw: boolean | ResolveByIdentityKeyOptions | ResolveByAttributesOptions | undefined
+): { useContacts: boolean, parallel: boolean } {
+  if (raw === undefined) return { useContacts: false, parallel: false }
+  if (typeof raw === 'boolean') return { useContacts: raw, parallel: false }
+  const useContacts = raw.overrideWithContacts ?? raw.useContacts ?? false
+  return { useContacts, parallel: raw.parallel === true }
+}
+
 /**
  * IdentityClient lets you discover who others are, and let the world know who you are.
  */
@@ -153,99 +197,100 @@ export class IdentityClient {
   }
 
   /**
-   * Resolves displayable identity certificates, issued to a given identity key by a trusted certifier.
+   * Resolves displayable identity certificates issued to a given identity key.
+   *
+   * **Default behavior (changed): contacts are NOT consulted.** Most clients have no
+   * contacts saved locally, so the previous "contacts-first" default paid setup cost for no
+   * gain. Pass `{ useContacts: true }` to opt in — appropriate when you know the user has
+   * saved contacts and prefers a local hit over a fresh overlay answer.
    *
-   * By default, contacts are consulted first and the overlay is only queried on a contacts miss.
-   * Pass `{ parallel: true }` to fire both in parallel (the legacy behavior, useful when callers
-   * specifically want a fresh overlay answer even when a contact exists).
+   * When `useContacts: true`:
+   *  - Default short-circuits: if a contact matches, the overlay is skipped entirely.
+   *  - `{ parallel: true }` fires contacts and overlay in parallel; contact wins on hit.
    *
    * @param args - Arguments for requesting the discovery based on the identity key.
-   * @param overrideWithContacts - Whether to consult personal contacts. Default true. When `false`,
-   *   contacts are skipped entirely and the overlay is queried directly. Boolean kept for legacy
-   *   call sites; new code should prefer the options-object form.
-   * @returns The promise resolves to displayable identities.
+   * @param opts - Boolean (legacy) or options object. Boolean `true` ≡ `{ useContacts: true }`.
    */
   async resolveByIdentityKey (
     args: DiscoverByIdentityKeyArgs,
-    overrideWithContacts: boolean | ResolveByIdentityKeyOptions = true
+    opts: boolean | ResolveByIdentityKeyOptions = false
   ): Promise<DisplayableIdentity[]> {
-    const opts: ResolveByIdentityKeyOptions =
-      typeof overrideWithContacts === 'boolean'
-        ? { overrideWithContacts }
-        : { overrideWithContacts: true, ...overrideWithContacts }
-    const useContacts = opts.overrideWithContacts !== false
-    const parallel = opts.parallel === true
-
-    if (useContacts && !parallel) {
+    const { useContacts, parallel } = normalizeOpts(opts)
+
+    // Fast path: skip contacts entirely. Default — straight overlay query,
+    // no listOutputs / decrypt / cache churn.
+    if (!useContacts) {
+      const certificatesResult = await this.wallet.discoverByIdentityKey(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      return await IdentityClient.parseIdentities(certs)
+    }
+
+    if (!parallel) {
       const contacts = await this.contactsManager.getContacts(args.identityKey)
       if (contacts.length > 0) return contacts
 
       const certificatesResult = await this.wallet.discoverByIdentityKey(args, this.originator)
       const certs = certificatesResult?.certificates ?? []
-      return certs.map((cert) => IdentityClient.parseIdentity(cert))
+      return await IdentityClient.parseIdentities(certs)
     }
 
     const [contacts, certificatesResult] = await Promise.all([
-      useContacts
-        ? this.contactsManager.getContacts(args.identityKey)
-        : Promise.resolve([] as Contact[]),
+      this.contactsManager.getContacts(args.identityKey),
       this.wallet.discoverByIdentityKey(args, this.originator)
     ])
 
     if (contacts.length > 0) return contacts
     const certs = certificatesResult?.certificates ?? []
-    return certs.map((cert) => IdentityClient.parseIdentity(cert))
+    return await IdentityClient.parseIdentities(certs)
   }
 
   /**
-   * Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
+   * Resolves displayable identity certificates by specific identity attributes.
    *
-   * By default, contacts are consulted first: if any contact matches, the overlay call is skipped
-   * entirely. Set `parallel: true` to keep the legacy parallel behavior.
+   * **Default behavior (changed): contacts are NOT consulted.** See
+   * {@link resolveByIdentityKey} for the reasoning. Pass `{ useContacts: true }` to opt in.
    *
    * @param args - Attributes and optional parameters used to discover certificates.
-   * @param overrideWithContacts - Whether to consult personal contacts. Default true. Boolean kept
-   *   for legacy call sites; new code should prefer the options-object form.
-   * @returns The promise resolves to displayable identities.
+   * @param opts - Boolean (legacy) or options object. Boolean `true` ≡ `{ useContacts: true }`.
    */
   async resolveByAttributes (
     args: DiscoverByAttributesArgs,
-    overrideWithContacts: boolean | ResolveByAttributesOptions = true
+    opts: boolean | ResolveByAttributesOptions = false
   ): Promise<DisplayableIdentity[]> {
-    const opts: ResolveByAttributesOptions =
-      typeof overrideWithContacts === 'boolean'
-        ? { overrideWithContacts }
-        : { overrideWithContacts: true, ...overrideWithContacts }
-    const useContacts = opts.overrideWithContacts !== false
-    const parallel = opts.parallel === true
-
-    if (useContacts && !parallel) {
+    const { useContacts, parallel } = normalizeOpts(opts)
+
+    // Fast path: skip contacts entirely.
+    if (!useContacts) {
+      const certificatesResult = await this.wallet.discoverByAttributes(args, this.originator)
+      const certs = certificatesResult?.certificates ?? []
+      return await IdentityClient.parseIdentities(certs)
+    }
+
+    if (!parallel) {
       const contacts = await this.contactsManager.getContacts()
       const matches = this.matchContactsByAttributes(contacts, args)
       if (matches.length > 0) return matches
 
       const certificatesResult = await this.wallet.discoverByAttributes(args, this.originator)
       const certs = certificatesResult?.certificates ?? []
+      if (contacts.length === 0) return await IdentityClient.parseIdentities(certs)
       const contactByKey = new Map<PubKeyHex, Contact>(
         contacts.map((contact) => [contact.identityKey, contact] as const)
       )
-      return certs.map(
-        (cert) => contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
-      )
+      return await IdentityClient.parseIdentitiesWithOverrides(certs, contactByKey)
     }
 
     const [contacts, certificatesResult] = await Promise.all([
-      useContacts ? this.contactsManager.getContacts() : Promise.resolve([] as Contact[]),
+      this.contactsManager.getContacts(),
       this.wallet.discoverByAttributes(args, this.originator)
     ])
 
+    const certs = certificatesResult?.certificates ?? []
+    if (contacts.length === 0) return await IdentityClient.parseIdentities(certs)
     const contactByKey = new Map<PubKeyHex, Contact>(
       contacts.map((contact) => [contact.identityKey, contact] as const)
     )
-    const certs = certificatesResult?.certificates ?? []
-    return certs.map(
-      (cert) => contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
-    )
+    return await IdentityClient.parseIdentitiesWithOverrides(certs, contactByKey)
   }
 
   /**
@@ -410,6 +455,45 @@ export class IdentityClient {
     return await this.contactsManager.removeContact(identityKey)
   }
 
+  /**
+   * Parse an array of certificates into DisplayableIdentity records, yielding to the
+   * event loop every {@link PARSE_BATCH_SIZE} entries so large result sets don't hog
+   * the main thread. Equivalent to `certs.map(parseIdentity)` for small inputs.
+   */
+  static async parseIdentities (certs: IdentityCertificate[]): Promise<DisplayableIdentity[]> {
+    const n = certs.length
+    if (n <= PARSE_BATCH_SIZE) {
+      return certs.map((c) => IdentityClient.parseIdentity(c))
+    }
+    const out: DisplayableIdentity[] = new Array(n)
+    for (let i = 0; i < n; i++) {
+      out[i] = IdentityClient.parseIdentity(certs[i])
+      if ((i + 1) % PARSE_BATCH_SIZE === 0) await yieldToEventLoop()
+    }
+    return out
+  }
+
+  /**
+   * Same as {@link parseIdentities} but consults a contact override map keyed by subject
+   * identity key. Used by `resolveByAttributes` when contacts are loaded.
+   */
+  static async parseIdentitiesWithOverrides (
+    certs: IdentityCertificate[],
+    contactByKey: Map<PubKeyHex, Contact>
+  ): Promise<DisplayableIdentity[]> {
+    const n = certs.length
+    if (n <= PARSE_BATCH_SIZE) {
+      return certs.map((cert) => contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert))
+    }
+    const out: DisplayableIdentity[] = new Array(n)
+    for (let i = 0; i < n; i++) {
+      const cert = certs[i]
+      out[i] = contactByKey.get(cert.subject) ?? IdentityClient.parseIdentity(cert)
+      if ((i + 1) % PARSE_BATCH_SIZE === 0) await yieldToEventLoop()
+    }
+    return out
+  }
+
   /**
    * Parse out identity and certifier attributes to display from an IdentityCertificate
    * @param identityToParse - The Identity Certificate to parse

package/src/identity/__tests/IdentityClient.additional.test.ts

@@ -571,7 +571,7 @@ describe('IdentityClient (additional coverage)', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const result = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } })
+      const result = await identityClient.resolveByAttributes({ attributes: { email: 'alice@example.com' } }, { useContacts: true })
       expect(result[0].name).toBe('Alice From Contact')
     })
 
@@ -764,4 +764,153 @@ describe('IdentityClient (additional coverage)', () => {
       expect(mockContactsManager.removeContact).toHaveBeenCalledWith('key-to-remove')
     })
   })
+
+  // ─── useContacts branches in resolveByIdentityKey / resolveByAttributes ─────
+
+  // Shared helpers — extracted to keep new tests DRY (avoid Sonar duplication gate).
+  const xCert = (subject: string, userName: string): any => ({
+    type: KNOWN_IDENTITY_TYPES.xCert,
+    subject,
+    decryptedFields: { userName, profilePhoto: '' },
+    certifierInfo: { name: 'CX', iconUrl: '' }
+  })
+  const emailCertOf = (subject: string, email: string): any => ({
+    type: KNOWN_IDENTITY_TYPES.emailCert,
+    subject,
+    decryptedFields: { email },
+    certifierInfo: { name: 'EC', iconUrl: '' }
+  })
+  const contactOf = (name: string, identityKey: string): any => ({
+    name, identityKey, avatarURL: '', abbreviatedKey: '', badgeIconURL: '', badgeLabel: '', badgeClickURL: ''
+  })
+  const stubDiscoveryByKey = (contacts: any[], certificates: any[]): void => {
+    identityClient['contactsManager'].getContacts = jest.fn().mockResolvedValue(contacts)
+    walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates })
+  }
+  const stubDiscoveryByAttr = (contacts: any[], certificates: any[]): void => {
+    identityClient['contactsManager'].getContacts = jest.fn().mockResolvedValue(contacts)
+    walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates })
+  }
+
+  describe('resolveByIdentityKey with useContacts opt-in', () => {
+    it('contacts miss falls through to overlay (sequential)', async () => {
+      stubDiscoveryByKey([], [xCert('k1', 'XUser')])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k1' }, { useContacts: true })
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
+      expect(result[0].name).toBe('XUser')
+    })
+
+    it('parallel mode returns contact on hit even though overlay runs', async () => {
+      const contact = contactOf('Cached Alice', 'k2')
+      stubDiscoveryByKey([contact], [])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k2' }, { useContacts: true, parallel: true })
+      expect(walletMock.discoverByIdentityKey).toHaveBeenCalled()
+      expect(result).toEqual([contact])
+    })
+
+    it('parallel mode contacts miss returns parsed overlay results', async () => {
+      stubDiscoveryByKey([], [xCert('k3', 'XOnly')])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k3' }, { useContacts: true, parallel: true })
+      expect(result[0].name).toBe('XOnly')
+    })
+
+    it('legacy boolean opt-in (true) consults contacts', async () => {
+      stubDiscoveryByKey([contactOf('Legacy True', 'k4')], [])
+      const result = await identityClient.resolveByIdentityKey({ identityKey: 'k4' }, true)
+      expect(result[0].name).toBe('Legacy True')
+      expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
+    })
+
+    it('overrideWithContacts legacy alias takes precedence over useContacts', async () => {
+      stubDiscoveryByKey([contactOf('Override Wins', 'k5')], [])
+      const result = await identityClient.resolveByIdentityKey(
+        { identityKey: 'k5' },
+        { useContacts: false, overrideWithContacts: true }
+      )
+      expect(result[0].name).toBe('Override Wins')
+    })
+  })
+
+  describe('resolveByAttributes with useContacts opt-in', () => {
+    it('contacts no-match falls through to overlay with contact overrides applied', async () => {
+      stubDiscoveryByAttr([contactOf('Override Alice', 'k-over')], [emailCertOf('k-over', 'alice@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'alice@example.com' } },
+        { useContacts: true }
+      )
+      expect(result[0].name).toBe('Override Alice')
+    })
+
+    it('contacts empty + overlay miss returns empty', async () => {
+      stubDiscoveryByAttr([], [])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'nobody@example.com' } },
+        { useContacts: true }
+      )
+      expect(result).toEqual([])
+    })
+
+    it('parallel mode with no contacts parses overlay only', async () => {
+      stubDiscoveryByAttr([], [emailCertOf('no-contact-key', 'lone@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'lone@example.com' } },
+        { useContacts: true, parallel: true }
+      )
+      expect(result[0].name).toBe('lone@example.com')
+    })
+
+    it('parallel mode with contacts applies overrides on overlay results', async () => {
+      stubDiscoveryByAttr([contactOf('Parallel Contact', 'pk')], [emailCertOf('pk', 'p@example.com')])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { email: 'p@example.com' } },
+        { useContacts: true, parallel: true }
+      )
+      expect(result[0].name).toBe('Parallel Contact')
+    })
+
+    it('matchContactsByAttributes ignores non-string attribute values', async () => {
+      stubDiscoveryByAttr([contactOf('X', 'kkkk')], [])
+      const result = await identityClient.resolveByAttributes(
+        { attributes: { count: 5 as unknown as string } },
+        { useContacts: true }
+      )
+      // No string-valued attrs → matchContactsByAttributes returns [] → overlay path
+      expect(walletMock.discoverByAttributes).toHaveBeenCalled()
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('parseIdentities batched path', () => {
+    it('yields to event loop when batch > PARSE_BATCH_SIZE', async () => {
+      const certs = Array.from({ length: 64 }, (_, i) => xCert(`subject-${i}`, `user-${i}`))
+      const result = await IdentityClient.parseIdentities(certs)
+      expect(result).toHaveLength(64)
+      expect(result[63].name).toBe('user-63')
+    })
+
+    it('parseIdentitiesWithOverrides batches with overrides applied', async () => {
+      const certs = Array.from({ length: 50 }, (_, i) => xCert(`subject-${i}`, `user-${i}`))
+      const overrideMap = new Map<string, any>([
+        ['subject-5', contactOf('Override 5', 'subject-5')],
+        ['subject-40', contactOf('Override 40', 'subject-40')]
+      ])
+      const result = await IdentityClient.parseIdentitiesWithOverrides(certs, overrideMap)
+      expect(result[5].name).toBe('Override 5')
+      expect(result[40].name).toBe('Override 40')
+      expect(result[6].name).toBe('user-6')
+    })
+  })
+
+  describe('yieldToEventLoop scheduler.yield path', () => {
+    const origScheduler = (globalThis as any).scheduler
+    afterEach(() => { (globalThis as any).scheduler = origScheduler })
+
+    it('uses scheduler.yield when available', async () => {
+      const yieldFn = jest.fn().mockResolvedValue(undefined)
+      ;(globalThis as any).scheduler = { yield: yieldFn }
+      const certs = Array.from({ length: 64 }, (_, i) => xCert(`s-${i}`, `u-${i}`))
+      await IdentityClient.parseIdentities(certs)
+      expect(yieldFn).toHaveBeenCalled()
+    })
+  })
 })

package/src/identity/__tests/IdentityClient.test.ts

@@ -260,11 +260,11 @@ describe('IdentityClient', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByIdentityKey = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'alice-identity-key' })
+      const identities = await identityClient.resolveByIdentityKey({ identityKey: 'alice-identity-key' }, { useContacts: true })
 
       expect(identities).toHaveLength(1)
       expect(identities[0].name).toBe('Alice Smith (Personal Contact)') // Contact should be returned, not discovered identity
-      // New default: contacts-first short-circuit — the overlay is skipped entirely on a contacts hit.
+      // With useContacts opt-in, contacts hit short-circuits the overlay query entirely.
       expect(walletMock.discoverByIdentityKey).not.toHaveBeenCalled()
     })
 
@@ -284,7 +284,7 @@ describe('IdentityClient', () => {
 
       const identities = await identityClient.resolveByIdentityKey(
         { identityKey: 'alice-identity-key' },
-        { parallel: true }
+        { useContacts: true, parallel: true }
       )
 
       expect(identities).toHaveLength(1)
@@ -380,7 +380,7 @@ describe('IdentityClient', () => {
       mockContactsManager.getContacts = jest.fn().mockResolvedValue([contact])
       walletMock.discoverByAttributes = jest.fn().mockResolvedValue({ certificates: [discoveredCertificate] })
 
-      const identities = await identityClient.resolveByAttributes({ attributes: { name: 'Alice' } })
+      const identities = await identityClient.resolveByAttributes({ attributes: { name: 'Alice' } }, { useContacts: true })
 
       expect(identities).toHaveLength(1)
       expect(identities[0].name).toBe('Alice Smith (Personal)') // Contact should be returned, not discovered identity