libp2r2p 0.11.22 → 0.11.23

package/README.md

@@ -264,7 +264,36 @@ close. Missing-key retries have no polling timer. MAC failures permit three tota
 attempts, persisted across reloads; exhausted packets remain until FIFO eviction.
 `retryPendingDecryptions({ force: true })` explicitly retries exhausted packets.
 Success enters the normal acknowledged inbox before removing the pending item.
-The session coordinator forwards this API. Private-channel consumers may opt in
+The session coordinator forwards this API.
+
+Pending recovery waits for 250 ms without channel setup, live/history processing
+or publication activity. Session foreground persistence/publication also delays
+it. After at most five seconds of eligible waiting, a busy channel may advance
+one packet, then receives a fresh deadline. Idle channels take batches of up to
+four records, yielding a task between every record. A busy channel does not hold
+up other channels; overdue channels precede the preferred foreground channel.
+Only requested passes run: a missing key never starts a polling loop. Timer
+throttling or an in-flight signer/storage call can extend actual elapsed time.
+
+`pendingDecryptionReady` defaults to `true` on messenger/session construction.
+Apps may pass `false` and call `setPendingDecryptionReady(true)` after their
+initial interface is presented; `false` holds only pending recovery, not live
+reception, publication or channel setup. The idle/deadline windows start after
+release. `setPendingDecryptionPriority(pubkey | null)` selects a channel on the
+messenger or a peer on the session; self-chat/`null` clear the session preference.
+The session retains a peer preference until preparation finishes and clears it
+on peer removal. Keep startup release and account lifecycle fencing in the app.
+
+`retryPendingDecryptions()` resolves after the requested scheduled pass (including
+an aggregated follow-up). `force: true` only overrides the MAC attempt ceiling;
+it does not bypass availability or admission. Requests before the first snapshot
+share that pass; requests during it aggregate into one following pass. Queue
+reads wait for initial release. Each packet is revalidated under the identity
+Web Lock when available; waits hold neither that lock nor the normal inbox/IDB
+queues. Fragment assembly survives scheduling boundaries. Pause/close cancel
+waits; channel removal fences its queued and in-flight results.
+
+Private-channel consumers may opt in
 with `onDecryptionFailure({ error, record })`, returning true only after durable
 handling, and replay records with `replayDeferredDecryptions`. Without the hook,
 standalone readers retain their existing error behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.11.22",
+  "version": "0.11.23",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/private-channel/index.js

@@ -717,7 +717,7 @@ function createProcessor ({
   onNymEvent,
   onSeedEvent,
   onContentKeyUsage,
-  onDecryptionFailure, isDecryptionPending,
+  onDecryptionFailure, isDecryptionPending, _onProcessing,
   onError,
   receivedChunkScope = '',
   receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS,
@@ -741,7 +741,14 @@ function createProcessor ({
   storeReady.catch(() => {})
 
   async function processOuterEvent (outer) {
-    await storeReady
+    const release = _onProcessing?.(outer.pubkey)
+    try {
+      await storeReady
+      return await processReadyOuterEvent(outer)
+    } finally { release?.() }
+  }
+
+  async function processReadyOuterEvent (outer) {
     let groupKey = ''
     let routerDecrypted = false
     try {
@@ -982,7 +989,7 @@ function shouldIgnoreGroupError (err) {
 
 // Replay ciphertext only. Keep one fragment processor for the entire batch;
 // incomplete outer groups remain pending until a later key/channel transition.
-export async function replayDeferredDecryptions ({ records, onRecovered, onFailure, ...options }) {
+export async function replayDeferredDecryptions ({ records, onRecovered, onFailure, _runRecord = (_record, work) => work(), ...options }) {
   if (!Array.isArray(records) || records.some(record => typeof record?.id !== 'string' ||
       typeof record.channelPubkey !== 'string' || !['outer_v1', 'routerRow_v1'].includes(record.packet?.format))) throw new ValidationError('INVALID_DEFERRED_RECORDS')
   if (typeof onRecovered !== 'function' || typeof onFailure !== 'function') throw new ValidationError('DEFERRED_CALLBACKS_REQUIRED')
@@ -1017,44 +1024,48 @@ export async function replayDeferredDecryptions ({ records, onRecovered, onFailu
   })
   try {
     for (const record of records) {
-      options.signal?.throwIfAborted()
-      current = record
-      chunked = false
-      try {
-        if (record.packet.format === 'outer_v1') {
-          await processor(record.packet.outer)
-          if (!chunked) await onRecovered(record)
-        } else {
-          const event = await unwrapRouterEvent({
-            receiverSigner: options.receiverSigner, receiverPubkey: options.receiverPubkey,
-            channelPubkey: record.channelPubkey, router: record.packet.router
-          })
-          options.signal?.throwIfAborted()
-          if (event) {
-            await options.onEvent?.(event, record.packet.outer, {
-              router: record.packet.router, channelPubkey: record.channelPubkey,
-              ...deliveryInfo(event, readSenderTag(record.packet.router))
+      await _runRecord(record, async () => {
+        options.signal?.throwIfAborted()
+        current = record
+        chunked = false
+        try {
+          if (record.packet.format === 'outer_v1') {
+            await processor(record.packet.outer)
+            if (!chunked) await onRecovered(record)
+          } else {
+            const event = await unwrapRouterEvent({
+              receiverSigner: options.receiverSigner, receiverPubkey: options.receiverPubkey,
+              channelPubkey: record.channelPubkey, router: record.packet.router
             })
+            options.signal?.throwIfAborted()
+            if (event) {
+              await options.onEvent?.(event, record.packet.outer, {
+                router: record.packet.router, channelPubkey: record.channelPubkey,
+                ...deliveryInfo(event, readSenderTag(record.packet.router))
+              })
+            }
+            await onRecovered(record)
           }
-          await onRecovered(record)
+        } catch (error) {
+          options.signal?.throwIfAborted()
+          await onFailure(record, decryptionError(error, { channelPubkey: record.channelPubkey, eventId: record.packet.outer?.id }))
         }
-      } catch (error) {
-        options.signal?.throwIfAborted()
-        await onFailure(record, decryptionError(error, { channelPubkey: record.channelPubkey, eventId: record.packet.outer?.id }))
-      }
+        for (const key of completed) {
+          for (const id of groups.get(key) || []) {
+            const recovered = records.find(record => record.id === id)
+            if (recovered) await onRecovered(recovered)
+          }
+          groups.delete(key)
+        }
+        completed.clear()
+      })
       // Let live ingestion and foreground signer work run between records.
       await new Promise(resolve => setTimeout(resolve, 0))
     }
-    for (const key of completed) {
-      for (const id of groups.get(key) || []) {
-        const record = records.find(record => record.id === id)
-        if (record) await onRecovered(record)
-      }
-    }
   } finally { processor.close() }
 }
 
-export async function fetch ({ signal, receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, onError, since, until, limit, mode = 'leecher', modeByPubkey, receivedChunkScope = '', receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _getEvents = getEvents }) {
+export async function fetch ({ signal, receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, _onProcessing, onError, since, until, limit, mode = 'leecher', modeByPubkey, receivedChunkScope = '', receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _getEvents = getEvents }) {
   if (!relays?.length) throw new ValidationError('NO_RELAYS')
   const authors = privateChannelPubkeyList({ privateChannelPubkey, privateChannelPubkeys })
   const filter = { kinds: [PRIVATE_BROADCAST_KIND] }
@@ -1073,7 +1084,7 @@ export async function fetch ({ signal, receiverSigner, iykcSigner, privateChanne
   const elapsedMs = Math.round(performance.now() - startedAt)
   const events = result.map(({ event }) => event)
   events.sort((a, b) => a.created_at - b.created_at)
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, _onProcessing, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   try {
     for (const event of events) {
       signal?.throwIfAborted()
@@ -1103,7 +1114,7 @@ export async function fetchHistory ({ receiverSigner, privateChannelSigner = rec
   } finally { processOuterEvent.close() }
 }
 
-export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, onError, since = nowSeconds() - 5, limit, liveOnly = false, mode = 'leecher', modeByPubkey, receivedChunkScope = '', receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _liveEventsGenerator = getLiveEventsGenerator, _eventsFeedGenerator = getEventsFeedGenerator }) {
+export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, _onProcessing, onError, since = nowSeconds() - 5, limit, liveOnly = false, mode = 'leecher', modeByPubkey, receivedChunkScope = '', receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _liveEventsGenerator = getLiveEventsGenerator, _eventsFeedGenerator = getEventsFeedGenerator }) {
   if (!relays?.length) throw new ValidationError('NO_RELAYS')
   if (receiverSigner && !receiverSigner?.nip44DecryptDoubleDH && !receiverSigner?.nip44v3Decrypt) throw new ValidationError('RECEIVER_SIGNER_NIP44V3_DECRYPT_UNSUPPORTED')
   if (!privateChannelReaderSigner && !privateChannelReaderSignersByPubkey && !privateChannelSigner && !privateChannelSignersByPubkey) throw new ValidationError('PRIVATE_CHANNEL_READER_REQUIRED')
@@ -1112,7 +1123,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
   const filter = { kinds: [PRIVATE_BROADCAST_KIND], since }
   if (authors.length) filter.authors = authors
   if (limit != null) filter.limit = limit
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, _onProcessing, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   const controller = new AbortController()
   const events = liveOnly
     ? _liveEventsGenerator(filter, relays, {

package/private-message/index.js

@@ -477,6 +477,7 @@ export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearT
           return dispatchSeedEvent(seed)
         },
         onContentKeyUsage: dispatchContentKeyUsage,
+        _onProcessing: pubkey => watchCallbacks(pubkey)._onProcessing?.(pubkey),
         isDecryptionPending: record => watchCallbacks(record.channelPubkey).isDecryptionPending?.(record),
         onDecryptionFailure: failure => watchCallbacks(failure.record.channelPubkey).onDecryptionFailure?.(failure),
         onError: err => reportSubscriptionError(channels, err)
@@ -524,7 +525,7 @@ export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearT
     onSeed,
     onChunk,
     onContentKeyUsage,
-    onDecryptionFailure, isDecryptionPending,
+    onDecryptionFailure, isDecryptionPending, _onProcessing,
     onSubscriptionState,
     onError,
     receivedChunkTtlMs,
@@ -545,7 +546,7 @@ export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearT
     const ownPubkey = receiverPubkey || await receiverSigner?.getPublicKey?.()
     if (identity !== undefined && identity !== ownPubkey) throw new ValidationError('PRIVATE_MESSAGE_IDENTITY_MISMATCH')
     identity = ownPubkey
-    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, onSubscriptionState, onError }
+    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onDecryptionFailure, isDecryptionPending, _onProcessing, onSubscriptionState, onError }
 
     for (const channel of channelList) {
       if (watchRequests.get(channel) !== request) continue

package/private-messenger/index.js

@@ -56,6 +56,7 @@ import { normalizeRelayUrl } from '../url/index.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { migrateMessageQueue } from './services/migrate-message-queue.js'
 import { createPendingDecryption } from './services/pending-decryption.js'
+import { createDecryptionScheduler } from './services/decryption-scheduler.js'
 import { decryptionError, isDeferredDecryptionError } from '../private-channel/helpers/decryption-error.js'
 import { bytesToBase64 } from '../base64/index.js'
 import { ValidationError } from '../error/index.js'
@@ -236,6 +237,7 @@ export class PrivateMessenger {
     autoDeletionCapability = true,
     _indexedDB = globalThis.indexedDB,
     useContentKeys = true,
+    pendingDecryptionReady = true,
     onContentKeyChange,
     onMessageQueued,
     onStateChanged,
@@ -248,6 +250,8 @@ export class PrivateMessenger {
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
     _isOnline = isOnline,
     _waitForForeground,
+    _observeForeground,
+    _now = Date.now,
     _onOnline = onOnline,
     _random = Math.random,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
@@ -259,6 +263,7 @@ export class PrivateMessenger {
     _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
     if (onStateChanged != null && typeof onStateChanged !== 'function') throw new ValidationError('INVALID_ON_STATE_CHANGED')
+    if (typeof pendingDecryptionReady !== 'boolean') throw new ValidationError('INVALID_PENDING_DECRYPTION_READY')
     this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
     this.fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
@@ -383,6 +388,9 @@ export class PrivateMessenger {
     this.closePromise = null
     this.initSettledPromise = null
     this.initialized = false
+    this.pendingDecryptionReady = pendingDecryptionReady
+    this.decryptionScheduler = createDecryptionScheduler({ ready: pendingDecryptionReady, now: _now, setTimer: _setTimeout, clearTimer: _clearTimeout })
+    this.stopDecryptionForeground = _observeForeground?.(active => this.decryptionScheduler.foreground(active))
     this.notifyStatus()
   }
 
@@ -1222,6 +1230,7 @@ export class PrivateMessenger {
           onSeed: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
           onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
           onDecryptionFailure: failure => this.deferDecryption(failure),
+          _onProcessing: pubkey => this.decryptionScheduler.activity(pubkey),
           isDecryptionPending: record => this.pendingDecryption.has(record),
           receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
           receivedChunkIndexedDB: this._indexedDB,
@@ -1734,7 +1743,10 @@ export class PrivateMessenger {
   unwatch (channels) {
     const pubkeys = channels ? uniq(Array.isArray(channels) ? channels : [channels]) : [...this.desiredChannels]
     for (const extension of this.extensions) extension.unwatch?.(pubkeys)
-    for (const pubkey of pubkeys) this.desiredChannels.delete(pubkey)
+    for (const pubkey of pubkeys) {
+      this.desiredChannels.delete(pubkey)
+      this.decryptionScheduler.remove(pubkey)
+    }
     for (const [key, pending] of this.pendingStorageWrites) if (pubkeys.includes(pending.record.channelPubkey)) this.pendingStorageWrites.delete(key)
     this.syncPauseRecovery()
     for (const pubkey of pubkeys) this.dropRecoveryState(pubkey)
@@ -1904,6 +1916,7 @@ export class PrivateMessenger {
       if (job) { jobs.push(job.work); continue }
       const controller = new AbortController()
       const channel = this.channels.get(pubkey)
+      const releaseActivity = this.decryptionScheduler.activity(pubkey)
       job = { controller, work: null }
       this.channelBackground.set(pubkey, job)
       const active = () => this.initialized && !controller.signal.aborted && !this.closePromise && !this.pauseReasons.size && this.channels.get(pubkey) === channel && this.desiredChannels.has(pubkey)
@@ -1940,6 +1953,7 @@ export class PrivateMessenger {
         throw error
       })
       job.work = Promise.race([work, cancelled]).finally(() => {
+        releaseActivity()
         controller.signal.removeEventListener('abort', stopAbort)
         if (this.channelBackground.get(pubkey) === job) this.channelBackground.delete(pubkey)
       })
@@ -1949,18 +1963,19 @@ export class PrivateMessenger {
     return jobs
   }
 
-  receive (pubkey, operation, message = {}) {
+  receive (pubkey, operation, message = {}, { trackActivity = true } = {}) {
     if (this.closePromise) {
       if (this.storageActive) this.recordInterruption([pubkey], messageTime(message))
       return Promise.reject(new Error('PRIVATE_MESSENGER_CLOSED'))
     }
+    const releaseActivity = trackActivity ? this.decryptionScheduler.activity(pubkey) : () => {}
     return this.queueIncoming(async () => {
       if (this.pauseReasons.size || !this.desiredChannels.has(pubkey)) {
         this.recordInterruption([pubkey], messageTime(message))
         throw this.pausedError()
       }
       return operation()
-    })
+    }).finally(releaseActivity)
   }
 
   nip65WatchChannelPubkeys () {
@@ -2274,180 +2289,204 @@ export class PrivateMessenger {
 
   async ask ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkey, relays, relayToReceivers, message, code, payload, error, content, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [receiverPubkey], relays, relayToReceivers })
-    this.debugSend('ask', channelPubkey, { code, receiverPubkey })
-    return this._privateMessage.ask({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      receiverPubkey,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      message,
-      code,
-      payload,
-      error,
-      content,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [receiverPubkey], relays, relayToReceivers })
+      this.debugSend('ask', channelPubkey, { code, receiverPubkey })
+      return await this._privateMessage.ask({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        receiverPubkey,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        message,
+        code,
+        payload,
+        error,
+        content,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async reply ({ channelPubkey = this.defaultChannelPubkey(), question, receiverPubkey, relays, relayToReceivers, message, code, payload, error, content, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const resolvedReceiverPubkey = receiverPubkey || question?.pubkey || ''
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [resolvedReceiverPubkey], relays, relayToReceivers })
-    this.debugSend('reply', channelPubkey, { code, receiverPubkey: receiverPubkey || question?.pubkey || '' })
-    return this._privateMessage.reply({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      question,
-      receiverPubkey,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      message,
-      code,
-      payload,
-      error,
-      content,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const resolvedReceiverPubkey = receiverPubkey || question?.pubkey || ''
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [resolvedReceiverPubkey], relays, relayToReceivers })
+      this.debugSend('reply', channelPubkey, { code, receiverPubkey: receiverPubkey || question?.pubkey || '' })
+      return await this._privateMessage.reply({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        question,
+        receiverPubkey,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        message,
+        code,
+        payload,
+        error,
+        content,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async tell ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkey, relays, relayToReceivers, message, code, payload, error, content, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [receiverPubkey], relays, relayToReceivers })
-    this.debugSend('tell', channelPubkey, { code, receiverPubkey })
-    return this._privateMessage.tell({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      receiverPubkey,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      message,
-      code,
-      payload,
-      error,
-      content,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys: [receiverPubkey], relays, relayToReceivers })
+      this.debugSend('tell', channelPubkey, { code, receiverPubkey })
+      return await this._privateMessage.tell({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        receiverPubkey,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        message,
+        code,
+        payload,
+        error,
+        content,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async yell ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, message, code, payload, error, content, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
-    this.debugSend('yell', channelPubkey, { code, receiverPubkeys })
-    return this._privateMessage.yell({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      receiverPubkeys,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      message,
-      code,
-      payload,
-      error,
-      content,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+      this.debugSend('yell', channelPubkey, { code, receiverPubkeys })
+      return await this._privateMessage.yell({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        receiverPubkeys,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        message,
+        code,
+        payload,
+        error,
+        content,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async broadcastRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
-    this.debugSend('broadcastRumor', channelPubkey, { receiverPubkeys })
-    return this._privateMessage.broadcastRumor({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      receiverPubkeys,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      rumor,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
+      this.debugSend('broadcastRumor', channelPubkey, { receiverPubkeys })
+      return await this._privateMessage.broadcastRumor({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        receiverPubkeys,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        rumor,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async broadcastEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
-    this.debugSend('broadcastEvent', channelPubkey, { receiverPubkeys })
-    return this._privateMessage.broadcastEvent({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      receiverPubkeys,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      temporaryStorageArea: this.temporaryStorageArea,
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      event,
-      onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
-      _getIykcProofs: this.contentKeyLookup()
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
+      this.debugSend('broadcastEvent', channelPubkey, { receiverPubkeys })
+      return await this._privateMessage.broadcastEvent({
+        senderSigner: this.userSigner,
+        imkcSigner: this.contentKeySigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        receiverPubkeys,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        temporaryStorageArea: this.temporaryStorageArea,
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        event,
+        onPreparedSeed: this.outgoingSeedHandler(channelPubkey),
+        _getIykcProofs: this.contentKeyLookup()
+      })
+    } finally { releaseActivity() }
   }
 
   async broadcastNymRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, nymSigner, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const resolvedNymSigner = this.requireNymSigner(channel, nymSigner)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
-    this.debugSend('broadcastNymRumor', channelPubkey, { receiverPubkeys })
-    return this._privateMessage.broadcastNymRumor({
-      nymSigner: resolvedNymSigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      rumor
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const resolvedNymSigner = this.requireNymSigner(channel, nymSigner)
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+      this.debugSend('broadcastNymRumor', channelPubkey, { receiverPubkeys })
+      return await this._privateMessage.broadcastNymRumor({
+        nymSigner: resolvedNymSigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        rumor
+      })
+    } finally { releaseActivity() }
   }
 
   async broadcastNymEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, nymSigner, deletionPubkey }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const resolvedNymSigner = this.requireNymSigner(channel, nymSigner)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
-    this.debugSend('broadcastNymEvent', channelPubkey, { receiverPubkeys })
-    return this._privateMessage.broadcastNymEvent({
-      nymSigner: resolvedNymSigner,
-      privateChannelSigner: channel.signer,
-      privateChannelReaderPubkey: channel.readerPubkey,
-      ...routing,
-      expirationSeconds: this.eventExpirationSecondsFor(channel),
-      deletionPubkey,
-      autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
-      event
-    })
+    const releaseActivity = this.decryptionScheduler.activity(channelPubkey)
+    try {
+      const resolvedNymSigner = this.requireNymSigner(channel, nymSigner)
+      const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+      this.debugSend('broadcastNymEvent', channelPubkey, { receiverPubkeys })
+      return await this._privateMessage.broadcastNymEvent({
+        nymSigner: resolvedNymSigner,
+        privateChannelSigner: channel.signer,
+        privateChannelReaderPubkey: channel.readerPubkey,
+        ...routing,
+        expirationSeconds: this.eventExpirationSecondsFor(channel),
+        deletionPubkey,
+        autoDeletionCapability: this.autoDeletionCapabilityFor(channel),
+        event
+      })
+    } finally { releaseActivity() }
   }
 
   async publishSeederPresence (channelPubkey = this.defaultChannelPubkey(), { signal } = {}) {
@@ -2881,6 +2920,7 @@ export class PrivateMessenger {
       onSeedEvent: seed => this.receive(channelPubkey, () => this.enqueueSeed(channelPubkey, seed), seed),
       onContentKeyUsage: usage => this.handleContentKeyUsage(channelPubkey, usage),
       onDecryptionFailure: failure => this.deferDecryption(failure),
+      _onProcessing: pubkey => this.decryptionScheduler.activity(pubkey),
       isDecryptionPending: record => this.pendingDecryption.has(record),
       onError: err => { throw err }
     }
@@ -3146,22 +3186,36 @@ export class PrivateMessenger {
     }
   }
 
+  setPendingDecryptionReady (ready) {
+    if (typeof ready !== 'boolean') throw new ValidationError('INVALID_PENDING_DECRYPTION_READY')
+    this.pendingDecryptionReady = ready
+    this.decryptionScheduler.setReady(ready)
+  }
+
+  setPendingDecryptionPriority (pubkey) {
+    if (pubkey !== null && !/^[0-9a-f]{64}$/.test(pubkey || '')) throw new ValidationError('INVALID_PENDING_DECRYPTION_PRIORITY')
+    this.decryptionScheduler.priority(pubkey)
+  }
+
   retryPendingDecryptions ({ force = false } = {}) {
     if (typeof force !== 'boolean') throw new ValidationError('INVALID_FORCE')
     if (this.closePromise || this.pauseReasons.size || !this.initialized) return Promise.resolve()
     if (this.decryptionRetry && !this.decryptionRetry.controller.signal.aborted) {
-      this.decryptionRetry.again = true
+      // Before a pass reads its snapshot, new requests belong to that pass.
+      if (this.decryptionRetry.started) this.decryptionRetry.again = true
       this.decryptionRetry.force ||= force
       return this.decryptionRetry.work
     }
-    const job = { controller: new AbortController(), again: false, force, work: null }
+    const job = { controller: new AbortController(), again: false, force, started: false, work: null }
     const previous = this.decryptionRetry?.work
     this.decryptionRetry = job
     const { signal } = job.controller
     const run = async () => {
       do {
+        await this.decryptionScheduler.waitReady(signal)
         signal.throwIfAborted()
         job.again = false
+        job.started = true
         const force = job.force
         job.force = false
         const groups = new Map()
@@ -3169,35 +3223,59 @@ export class PrivateMessenger {
           if (!groups.has(record.channelPubkey)) groups.set(record.channelPubkey, [])
           groups.get(record.channelPubkey).push(record)
         }
-        for (const [channelPubkey, records] of groups) {
-          signal.throwIfAborted()
+        const results = await Promise.allSettled([...groups].map(async ([channelPubkey, records]) => {
           const channel = this.channels.get(channelPubkey)
-          if (!channel || !this.desiredChannels.has(channelPubkey)) continue
-          const current = () => { signal.throwIfAborted(); if (this.channels.get(channelPubkey) !== channel) throw new Error('PRIVATE_CHANNEL_CHANGED') }
-          await this._privateChannel.replayDeferredDecryptions({
-            records, signal, receiverSigner: this.userSigner, receiverPubkey: this.userPubkey,
-            privateChannelSigner: channel.signer, privateChannelReaderSigner: channel.readerSigner,
-            privateChannelReaderPubkey: channel.readerPubkey, mode: channel.mode,
-            receivedChunkScope: `${this.prefix}:pending`, receivedChunkIndexedDB: this._indexedDB,
-            onEvent: (event, outer, meta) => {
-              current()
-              return this.receive(channelPubkey, () => this.enqueueRumor(eventType(event), channelPubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer })
-            },
-            onNymEvent: (event, outer, meta) => {
-              current()
-              return this.receive(channelPubkey, () => this.enqueueRumor('nym', channelPubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer })
-            },
-            onSeedEvent: seed => { current(); return this.receive(channelPubkey, () => this.enqueueSeed(channelPubkey, seed), seed) },
-            onRecovered: record => { current(); return this.pendingDecryption.recovered(record) },
-            onFailure: (record, error) => { current(); return this.pendingDecryption.failed(record, error) }
-          })
-        }
+          if (!channel || !this.desiredChannels.has(channelPubkey)) return
+          const current = () => {
+            signal.throwIfAborted()
+            if (this.pauseReasons.size || this.channels.get(channelPubkey) !== channel || !this.desiredChannels.has(channelPubkey)) throw new Error('PRIVATE_CHANNEL_CHANGED')
+          }
+          try {
+            await this._privateChannel.replayDeferredDecryptions({
+              records, signal, receiverSigner: this.userSigner, receiverPubkey: this.userPubkey,
+              privateChannelSigner: channel.signer, privateChannelReaderSigner: channel.readerSigner,
+              privateChannelReaderPubkey: channel.readerPubkey, mode: channel.mode,
+              receivedChunkScope: `${this.prefix}:pending`, receivedChunkIndexedDB: this._indexedDB,
+              _runRecord: async (record, process) => {
+                let done = false
+                while (!done) {
+                  current()
+                  done = await this.decryptionScheduler.run(channelPubkey, () => {
+                    const attempt = async () => {
+                      current()
+                      if (!this.pendingDecryptionReady) return false
+                      if (await this.pendingDecryption.current(record, { force })) await process()
+                      return true
+                    }
+                    const locks = globalThis.navigator?.locks
+                    return locks?.request ? locks.request(`${this.prefix}:pending-decryption:retry`, { signal }, attempt) : attempt()
+                  }, signal)
+                }
+              },
+              onEvent: (event, outer, meta) => {
+                current()
+                return this.receive(channelPubkey, () => this.enqueueRumor(eventType(event), channelPubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }, { trackActivity: false })
+              },
+              onNymEvent: (event, outer, meta) => {
+                current()
+                return this.receive(channelPubkey, () => this.enqueueRumor('nym', channelPubkey, { event, outer, meta, payload: parseEventContent(event) }), { event, outer }, { trackActivity: false })
+              },
+              onSeedEvent: seed => { current(); return this.receive(channelPubkey, () => this.enqueueSeed(channelPubkey, seed), seed, { trackActivity: false }) },
+              onRecovered: record => { current(); return this.pendingDecryption.recovered(record) },
+              onFailure: (record, error) => { current(); return this.pendingDecryption.failed(record, error) }
+            })
+          } catch (error) {
+            if (this.channels.get(channelPubkey) === channel && this.desiredChannels.has(channelPubkey)) throw error
+          } finally { this.decryptionScheduler.finish(channelPubkey) }
+        }))
+        const failed = results.find(result => result.status === 'rejected')
+        if (failed) throw failed.reason
+        job.started = false
       } while (job.again)
     }
-    job.work = Promise.resolve(previous).catch(() => {}).then(() => {
-      const locks = globalThis.navigator?.locks
-      return locks?.request ? locks.request(`${this.prefix}:pending-decryption:retry`, { signal }, run) : run()
-    }).catch(error => { if (!signal.aborted) throw error }).finally(() => {
+    job.work = Promise.resolve(previous).catch(() => {}).then(run).catch(error => {
+      if (!signal.aborted) throw error
+    }).finally(() => {
       if (this.decryptionRetry === job) this.decryptionRetry = null
     })
     return job.work
@@ -3256,6 +3334,8 @@ export class PrivateMessenger {
 
   close () {
     this.decryptionRetry?.controller.abort(new Error('PRIVATE_MESSENGER_CLOSED'))
+    this.decryptionScheduler.close()
+    this.stopDecryptionForeground?.()
     if (this.closePromise) return this.closePromise
     const initSettledPromise = this.initSettledPromise
     this.sendRoutingLifetime.abort()

package/private-messenger/services/decryption-scheduler.js

@@ -0,0 +1,135 @@
+// Admission only: never wait while holding an inbox operation, IDB transaction
+// or the cross-instance retry lock. A busy channel cannot stall another one.
+export function createDecryptionScheduler ({ ready = true, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  const channels = new Map()
+  const readyWaiters = new Set()
+  let timer
+  let running = false
+  let closed
+  let foreground = false
+  let foregroundAt = now()
+  let priority = null
+  let previous
+  let batch = 0
+  const stateFor = pubkey => {
+    if (!channels.has(pubkey)) channels.set(pubkey, { active: 0, at: now(), deadline: null, jobs: [] })
+    return channels.get(pubkey)
+  }
+  const quietAt = state => state.active || foreground ? Infinity : Math.max(state.at, foregroundAt) + 250
+  const schedule = () => {
+    if (timer !== undefined) clearTimer(timer)
+    timer = undefined
+    if (closed || !ready || running) return
+    const pending = [...channels.values()].filter(state => state.jobs.length)
+    if (!pending.length) return
+    const at = Math.min(...pending.map(state => Math.min(quietAt(state), state.deadline)))
+    timer = setTimer(pump, Math.max(0, at - now()))
+  }
+  async function pump () {
+    timer = undefined
+    if (closed || !ready || running) return
+    const time = now()
+    const eligible = [...channels].filter(([, state]) => state.jobs.length && Math.min(quietAt(state), state.deadline) <= time)
+    eligible.sort(([a, x], [b, y]) => {
+      const overdue = Number(y.deadline <= time) - Number(x.deadline <= time)
+      if (overdue) return overdue
+      if (x.deadline <= time && x.deadline !== y.deadline) return x.deadline - y.deadline
+      if (a === previous && batch >= 4) return 1
+      if (b === previous && batch >= 4) return -1
+      return Number(b === priority) - Number(a === priority)
+    })
+    if (!eligible.length) { schedule(); return }
+    const [pubkey, state] = eligible[0]
+    const job = state.jobs.shift()
+    running = true
+    if (previous === pubkey) batch++
+    else { previous = pubkey; batch = 1 }
+    try {
+      job.signal?.throwIfAborted()
+      job.resolve(await job.work())
+    } catch (error) { job.reject(error) } finally {
+      job.signal?.removeEventListener('abort', job.abort)
+      state.deadline = now() + 5000
+      running = false
+      // Always use a new task, including between records in the same batch.
+      schedule()
+    }
+  }
+  const rejectJobs = (state, error) => {
+    for (const job of state.jobs.splice(0)) {
+      job.signal?.removeEventListener('abort', job.abort)
+      job.reject(error)
+    }
+  }
+  return {
+    activity (pubkey) {
+      if (closed) return () => {}
+      const state = stateFor(pubkey)
+      state.active++; state.at = now(); schedule()
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        state.active--; state.at = now(); schedule()
+      }
+    },
+    foreground (active) { foreground = active; foregroundAt = now(); schedule() },
+    priority (pubkey) { priority = pubkey; schedule() },
+    setReady (value) {
+      if (ready === value || closed) return
+      ready = value
+      if (ready) {
+        for (const state of channels.values()) { state.at = now(); state.deadline = state.jobs.length ? now() + 5000 : null }
+        for (const wake of [...readyWaiters]) wake()
+      }
+      schedule()
+    },
+    async waitReady (signal) {
+      while (true) {
+        signal?.throwIfAborted()
+        if (closed) throw closed
+        if (ready) return
+        await new Promise((resolve, reject) => {
+          const finish = () => {
+            readyWaiters.delete(finish); signal?.removeEventListener('abort', finish)
+            if (closed || signal?.aborted) reject(closed || signal.reason)
+            else resolve()
+          }
+          readyWaiters.add(finish); signal?.addEventListener('abort', finish, { once: true })
+        })
+      }
+    },
+    run (pubkey, work, signal) {
+      signal?.throwIfAborted()
+      if (closed) return Promise.reject(closed)
+      const state = stateFor(pubkey)
+      state.deadline ??= now() + 5000
+      return new Promise((resolve, reject) => {
+        const job = { work, resolve, reject, signal }
+        job.abort = () => {
+          const index = state.jobs.indexOf(job)
+          if (index < 0) return
+          state.jobs.splice(index, 1); reject(signal.reason); schedule()
+        }
+        signal?.addEventListener('abort', job.abort, { once: true })
+        state.jobs.push(job); schedule()
+      })
+    },
+    remove (pubkey) {
+      const state = channels.get(pubkey)
+      if (state) rejectJobs(state, new Error('PRIVATE_CHANNEL_CHANGED'))
+      channels.delete(pubkey); schedule()
+    },
+    finish (pubkey) {
+      const state = channels.get(pubkey)
+      if (state && !state.jobs.length) state.deadline = null
+    },
+    close () {
+      closed ||= new Error('PRIVATE_MESSENGER_CLOSED')
+      if (timer !== undefined) clearTimer(timer)
+      for (const state of channels.values()) rejectJobs(state, closed)
+      channels.clear()
+      for (const wake of [...readyWaiters]) wake()
+    }
+  }
+}

package/private-messenger/services/pending-decryption.js

@@ -98,6 +98,12 @@ export async function createPendingDecryption ({ prefix, indexedDB, maxBytes = P
       for await (const item of queue.storedItems()) if (force || item.macAttempts < 3) records.push(item)
       return records
     },
+    current (item, { force = false } = {}) {
+      return serial(async () => {
+        const stored = await queue.getBy('byId', item.id)
+        return stored && (force || stored.macAttempts < 3) ? stored : null
+      })
+    },
     recovered (item) {
       return serial(async () => {
         await queue.removeBy('byId', item.id)

package/private-messenger/session/README.md

@@ -10,6 +10,19 @@ ordinary availability recovery already requests a pass. Ciphertext stays in the
 separate bounded FIFO until admitted to the normal inbox, evicted or explicitly
 cleared. This does not retry application storage/permission failures as crypto.
 
+Construction accepts `pendingDecryptionReady` (default `true`). Pass `false` to
+hold pending queue reads/replay until `setPendingDecryptionReady(true)` releases
+them after initial presentation. This never pauses live reception, sends or
+channel preparation. Recovery waits for 250 ms of channel inactivity; a five-second
+maximum admits one packet during sustained activity. It yields between records,
+with at most four consecutive preferred records before another eligible channel.
+`setPendingDecryptionPriority(peer | null)` retains a peer preference through
+preparation; self-chat/`null` or removal clear it. Deadlines prevent preference
+from starving other channels. Account unavailability/close still cancel recovery;
+`force` bypasses only the MAC attempt limit. Awaiting the retry API awaits its
+scheduled pass, so do not await it on the interface's critical startup path.
+
+
 Provide `owner`, a byte-based NIP-44 v3 `signer` with `withSharedKey`, and either
 `eventStore` or a `messageStorage.save(event, { peerPubkey, hearsay })` adapter.
 Optional `chunkStorage` and `recoveryStorage` (`seeds`, `authorizations`) select

package/private-messenger/session/helpers/foreground-work.js

@@ -3,15 +3,19 @@
 export function createForegroundWork () {
   let active = 0
   const waiters = new Set()
+  const observers = new Set()
+  const notify = () => { for (const listener of observers) listener(active > 0) }
   const lifetime = new AbortController()
   return {
     enter () {
       active++
+      notify()
       let released = false
       return () => {
         if (released) return
         released = true
         if (--active === 0) for (const wake of [...waiters]) wake()
+        notify()
       }
     },
     wait (signal) {
@@ -24,6 +28,7 @@ export function createForegroundWork () {
         combined.addEventListener('abort', finish, { once: true })
       })
     },
-    close () { lifetime.abort(); waiters.clear() }
+    observe (listener) { observers.add(listener); listener(active > 0); return () => observers.delete(listener) },
+    close () { lifetime.abort(); waiters.clear(); observers.clear() }
   }
 }

package/private-messenger/session/index.js

@@ -44,9 +44,11 @@ function messengerStatusSnapshot (value) {
   return { closed: value.closed, paused: value.paused, pauseReasons: [...value.pauseReasons] }
 }
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _isOnline = isOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, pendingDecryptionReady = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _isOnline = isOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
+  if (typeof pendingDecryptionReady !== 'boolean') throw new ValidationError('INVALID_PENDING_DECRYPTION_READY')
+  let pendingDecryptionPeer = null
   const reportedErrors = new WeakSet()
   const reportError = error => {
     if (error && (typeof error === 'object' || typeof error === 'function')) {
@@ -139,7 +141,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     let candidate
     try {
       candidate = await Messenger({
-        fallbackRelays, fallbackDelayMs, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys, _waitForForeground: foreground.wait,
+        fallbackRelays, fallbackDelayMs, pendingDecryptionReady, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys, _waitForForeground: foreground.wait, _observeForeground: foreground.observe,
         onMessageQueued: () => { if (messengerBinding === binding) return drain() },
         onStateChanged: state => {
           if (closed || messengerBinding !== binding) return
@@ -152,6 +154,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (typeof candidate?.readStatus !== 'function' || !notified) throw new ValidationError('MESSENGER_STATE_CONTRACT_REQUIRED')
       const status = messengerStatusSnapshot(candidate.readStatus())
       messenger = candidate
+      messenger.setPendingDecryptionReady?.(pendingDecryptionReady)
+      messenger.setPendingDecryptionPriority?.(channels.get(pendingDecryptionPeer)?.pubkey ?? null)
       stateChanged(status)
     } catch (error) {
       messengerBinding = null
@@ -168,6 +172,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       signal.throwIfAborted()
       const channel = { signer: scoped, pubkey, readerPubkey: pubkey, mode, seeders: seedersForPeer(peer) }
       channels.set(peer, channel)
+      if (peer === pendingDecryptionPeer) messenger?.setPendingDecryptionPriority?.(channel.pubkey)
       await schedule()
       signal.throwIfAborted()
       return channel
@@ -558,6 +563,16 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     await writeDownloadIntent(() => downloads?.remove(id))
   }
   return {
+    setPendingDecryptionReady (ready) {
+      if (typeof ready !== 'boolean') throw new ValidationError('INVALID_PENDING_DECRYPTION_READY')
+      pendingDecryptionReady = ready
+      if (!closed) messenger?.setPendingDecryptionReady?.(ready)
+    },
+    setPendingDecryptionPriority (peer) {
+      if (peer !== null && !/^[0-9a-f]{64}$/.test(peer || '')) throw new ValidationError('INVALID_PENDING_DECRYPTION_PRIORITY')
+      pendingDecryptionPeer = peer === owner ? null : peer
+      if (!closed) messenger?.setPendingDecryptionPriority?.(channels.get(pendingDecryptionPeer)?.pubkey ?? null)
+    },
     async retryPendingDecryptions (options) {
       if (closed || !available) return
       await ensureMessenger()
@@ -605,6 +620,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (next.size === peers.size && [...next].every(peer => peers.has(peer))) return configuring
       peers.clear(); for (const peer of next) peers.add(peer)
       preparation.reconcile(peers)
+      if (pendingDecryptionPeer && !peers.has(pendingDecryptionPeer)) {
+        pendingDecryptionPeer = null
+        messenger?.setPendingDecryptionPriority?.(null)
+      }
       for (const peer of channels.keys()) {
         if (!peers.has(peer)) {
           channels.delete(peer); pendingPriorityRanges.delete(peer)