libp2r2p 0.11.4 → 0.11.6

package/README.md

@@ -534,6 +534,42 @@ returned events; received messages may already have been queued. This is a
 history completeness failure, not evidence that an outgoing message failed.
 Existing rewatch/resume and relay-list refresh paths retry pending intervals;
 there is no dedicated periodic retry timer for a failed history fetch.
+`private-channel.fetchHistory(options)` (0.11.6) is the complete-interval API
+used by messenger recovery. It accepts the signers, processor/fragment options,
+callbacks and abort signal of `fetch`, plus inclusive `since`/`until` bounds
+(defaults: 0 and the start time of the call). It returns only
+`{ oldestCreatedAt, receivedEventCount, relays }`; an empty scan has a null oldest
+time. No complete-history event array is retained. `fetch` keeps its existing
+single-query array contract and optional limit.
+
+History queries each relay independently with limit 16. A response with 16 events
+or status `satisfied` is saturated, even if it already reports EOSE or contains
+fewer valid events. Saturated intervals split into nonoverlapping inclusive
+halves; completed pages process chronologically, oldest half first. Single-second
+intervals grow through 16, 32, 64, 128 and 256. Each response is also bounded to
+4 MiB of serialized UTF-8 event data. At the dense-second or volume ceiling,
+`PRIVATE_CHANNEL_FETCH_INCOMPLETE` retains the operational cause
+`PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT`; the interval stays pending. There is no
+nonstandard cursor, disk spool, dropped excess or successful incomplete scan.
+
+A fragment processor and the existing scoped fragment storage span the entire
+call, including pages and relays. Callbacks are awaited before requesting the
+next page. Processing/persistence failures propagate; completed pages may already
+be ingested and retries remain subject to the existing idempotence contract.
+The summary count includes processed outer events per relay, including replicas,
+not unique decrypted messages or discarded saturated probes. It does not include
+all events observed in those probes.
+
+Recovery admits at most two pages per PrivateMessenger and one per normalized
+relay across the same library instance, including page processing time. Continuous
+live watches are outside those recovery gates. Waiters are abortable and FIFO,
+with at most 256 queued per gate (`PRIVATE_CHANNEL_HISTORY_QUEUE_FULL` on excess).
+The five-second network timeout begins after admission; reported read time also
+includes admission but excludes processing. Seeders still supplement the oldest
+relay result. Checkpoints advance only after the entire interval and existing
+seeder stages succeed; interruption preserves its original pending range. No
+persisted state format changes or migrations are needed.
+
 Subscription relay errors forwarded to `onError` include `relay` when known
 and `operation: 'private-channel.subscribe'`. A per-notification wrapper retains
 the native message, name, code, category and WebSocket close fields; `cause`
@@ -915,10 +951,16 @@ local defaults, including a bounded streaming file cache. The optional
 provides reusable DM inbox/outbox and attachment lifecycle without UI coupling,
 including an optional `onSendError` callback identifying the failed outbox message.
 
-Single-recipient private messages now retry NIP-65 read relays in pairs when
+Private messages, including multi-recipient channels, retry NIP-65 read relays
+in pairs per recipient when
 selected relays reject publication or become unreachable while connectivity is
-confirmed. The exact encrypted outer events are reused; explicit per-call and
-channel relay overrides remain authoritative. Successful sends keep first-ACK
+confirmed. The exact encrypted outer events are reused. Optional `fallbackRelays` on
+`createPrivateMessenger` and `createPrivateMessageSession` are tried after the
+primary destinations, including explicit per-call `relays`, channel `sendRelays`
+and channel/global `relays`, as well as explicit `relayToReceivers` maps.
+Retries preserve each encrypted recipient subset; success requires accepted
+publication covering every recipient in that subset. Receive routing adds them from the start for live
+messages, history and files while preserving automatic NIP-65 updates. Successful sends keep first-ACK
 latency, and short-lived channel/recipient preferences avoid recently refused
 relays without changing receive subscriptions. See the
 [session coordinator](private-messenger/session/README.md) for deferred offline

package/helpers/abortable-semaphore.js

@@ -0,0 +1,41 @@
+// A bounded FIFO for asynchronous work. Acquired leases release explicitly;
+// queued cancellations never consume capacity or keep idle keyed gates alive.
+export function createAbortableSemaphore (capacity, onIdle = () => {}) {
+  const queue = []
+  let active = 0
+  const drain = () => {
+    while (active < capacity && queue.length) {
+      const job = queue.shift()
+      job.signal?.removeEventListener('abort', job.abort)
+      active++
+      let released = false
+      job.resolve(() => {
+        if (released) return
+        released = true
+        active--
+        drain()
+      })
+    }
+    if (!active && !queue.length) onIdle()
+  }
+  return {
+    acquire (signal) {
+      signal?.throwIfAborted()
+      if (queue.length >= 256) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
+      return new Promise((resolve, reject) => {
+        const job = {
+          signal, resolve, abort: () => {
+            const index = queue.indexOf(job)
+            if (index < 0) return
+            queue.splice(index, 1)
+            reject(signal.reason)
+            drain()
+          }
+        }
+        signal?.addEventListener('abort', job.abort, { once: true })
+        queue.push(job)
+        drain()
+      })
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -22,6 +22,7 @@
     "ecdh",
     "error",
     "event",
+    "helpers",
     "idb",
     "idb-queue",
     "index.js",

package/private-channel/helpers/history.js

@@ -0,0 +1,121 @@
+import { ValidationError } from '../../error/index.js'
+import { normalizeRelayUrl } from '../../url/index.js'
+import { createAbortableSemaphore } from '../../helpers/abortable-semaphore.js'
+import { incompleteFetchError } from './fetch-error.js'
+
+const PAGE_SIZE = 16
+const MAX_PAGE_SIZE = 256
+const MAX_PAGE_BYTES = 4 * 1024 * 1024
+const TIMEOUT_MS = 5000
+const relayGates = new Map()
+const encoder = new TextEncoder()
+const pageLimitError = () => Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT'), { code: 'PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT' })
+
+function acquireRelay (relay, signal) {
+  signal?.throwIfAborted()
+  let gate = relayGates.get(relay)
+  if (!gate) {
+    gate = createAbortableSemaphore(1, () => { if (relayGates.get(relay) === gate) relayGates.delete(relay) })
+    relayGates.set(relay, gate)
+  }
+  return gate.acquire(signal)
+}
+
+// Queries bounded temporal leaves, oldest first. A saturated one-second leaf
+// cannot be split using standard NIP-01; expand it only up to the safe ceiling.
+export async function readHistory ({ filter, relays, receiverPubkey, signal, getEvents, processEvent, acquirePage }) {
+  const since = filter.since ?? 0
+  const until = filter.until ?? Math.floor(Date.now() / 1000)
+  if (![since, until].every(value => Number.isSafeInteger(value) && value >= 0) || since > until) throw new ValidationError('INVALID_PRIVATE_CHANNEL_HISTORY_RANGE')
+  if (!Array.isArray(relays) || !relays.length) throw new ValidationError('NO_RELAYS')
+  const urls = [...new Set(relays.map(normalizeRelayUrl))]
+  const report = []
+  const errors = []
+  let oldestCreatedAt = null
+  let receivedEventCount = 0
+  let elapsedMs = 0
+  const process = async result => {
+    result.sort((a, b) => a.event.created_at - b.event.created_at || String(a.event.id).localeCompare(String(b.event.id)))
+    for (const { event } of result) {
+      signal?.throwIfAborted()
+      await processEvent(event)
+      receivedEventCount++
+      oldestCreatedAt = Math.min(oldestCreatedAt ?? event.created_at, event.created_at)
+    }
+  }
+  for (const relay of urls) {
+    const intervals = [{ since, until, limit: PAGE_SIZE }]
+    let outcome = { relay, status: 'eose' }
+    while (intervals.length) {
+      signal?.throwIfAborted()
+      const interval = intervals.pop()
+      const started = performance.now()
+      let releaseRelay
+      let releasePage
+      let page
+      try {
+        let bytes = 0
+        try {
+          releaseRelay = await acquireRelay(relay, signal)
+          releasePage = await acquirePage?.(signal)
+          signal?.throwIfAborted()
+          page = await getEvents({ ...filter, ...interval }, [relay], {
+            signal, timeout: TIMEOUT_MS, timeoutAfterFirstEose: null,
+            callback: item => {
+              if (item.type !== 'event') return
+              bytes += encoder.encode(JSON.stringify(item.event)).byteLength
+              if (bytes > MAX_PAGE_BYTES) throw pageLimitError()
+            }
+          })
+          // Also enforce the contract for injected readers that omit callbacks.
+          let resultBytes = 0
+          for (const { event } of page.result) {
+            resultBytes += encoder.encode(JSON.stringify(event)).byteLength
+            if (resultBytes > MAX_PAGE_BYTES) throw pageLimitError()
+          }
+        } catch (error) {
+          signal?.throwIfAborted()
+          errors.push({ relay, reason: error })
+          outcome = { relay, status: 'error', error }
+          break
+        } finally { elapsedMs += performance.now() - started }
+        signal?.throwIfAborted()
+        const status = page.relays?.find(item => item.relay === relay)
+        if (page.errors?.length || !status || !['eose', 'satisfied'].includes(status.status)) {
+          await process(page.result)
+          errors.push(...(page.errors ?? []))
+          outcome = status ?? { relay, status: 'error' }
+          break
+        }
+        if (status.status === 'satisfied' || page.result.length >= interval.limit) {
+          if (interval.since < interval.until) {
+            const middle = Math.floor(interval.since + (interval.until - interval.since) / 2)
+            intervals.push({ since: middle + 1, until: interval.until, limit: PAGE_SIZE }, { since: interval.since, until: middle, limit: PAGE_SIZE })
+          } else if (interval.limit < MAX_PAGE_SIZE) {
+            intervals.push({ ...interval, limit: interval.limit * 2 })
+          } else {
+            await process(page.result)
+            const error = pageLimitError()
+            errors.push({ relay, reason: error })
+            outcome = { relay, status: 'error', error }
+            break
+          }
+        } else {
+          await process(page.result)
+        }
+        signal?.throwIfAborted()
+      } finally {
+        releasePage?.()
+        releaseRelay?.()
+      }
+    }
+    report.push(outcome)
+  }
+  signal?.throwIfAborted()
+  if (errors.length || report.some(item => item.status !== 'eose')) {
+    const error = incompleteFetchError({ errors, report, receivedEventCount, elapsedMs: Math.round(elapsedMs), request: { relays: urls, channelPubkeys: filter.authors ?? [], receiverPubkey, since, until, limit: PAGE_SIZE, timeoutMs: TIMEOUT_MS } })
+    error.operation = 'private-channel.fetchHistory'
+    throw error
+  }
+  return { oldestCreatedAt, receivedEventCount, relays: report }
+}

package/private-channel/index.js

@@ -7,6 +7,7 @@ import { getIykcProofs } from '../content-key/index.js'
 import { ValidationError } from '../error/index.js'
 import { normalizeRumor, deliveryInfo } from './helpers/rumor.js'
 import { incompleteFetchError } from './helpers/fetch-error.js'
+import { readHistory } from './helpers/history.js'
 import { subscriptionError } from './helpers/subscription-error.js'
 import * as nip44v3 from '../nip44-v3/index.js'
 import { relayPool } from '../relay/index.js'
@@ -37,7 +38,7 @@ const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 const NIP44_V3_SCOPE = ''
 
-const sendToRelays = (...args) => relayPool.sendEvent(...args)
+const sendToRelays = (event, relays) => relayPool.sendEvent(event, relays)
 const getEvents = (...args) => relayPool.getEvents(...args)
 const getLiveEventsGenerator = (...args) => relayPool.getLiveEventsGenerator(...args)
 const getEventsFeedGenerator = (...args) => relayPool.getEventsFeedGenerator(...args)
@@ -540,7 +541,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
     try {
       for (const group of groups) {
         for await (const wrappedEvent of wrapPreparedEvents({ privateChannelSigner, receivers: group.receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })) {
-          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays)))
+          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(group.receivers), primaryRelays: group.relays }))
         }
       }
     } finally {
@@ -550,7 +551,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
   }
 
   for await (const wrappedEvent of wrapEvents({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, event, expirationSeconds, temporaryStorageArea, _getIykcProofs })) {
-    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays)))
+    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(receivers), primaryRelays: relays }))
   }
   return results
 }
@@ -955,6 +956,17 @@ export async function fetch ({ signal, receiverSigner, iykcSigner, privateChanne
   }
 }
 
+// Complete interval recovery with bounded pages and one fragment processor.
+// Existing fetch() retains its one-query/event-array contract.
+export async function fetchHistory ({ receiverSigner, privateChannelSigner = receiverSigner, _getEvents = getEvents, _acquirePage, ...options }) {
+  const authors = privateChannelPubkeyList(options)
+  const filter = { kinds: [PRIVATE_BROADCAST_KIND], ...(authors.length ? { authors } : {}), since: options.since, until: options.until }
+  const processOuterEvent = createProcessor({ ...options, receiverSigner, privateChannelSigner, onError: error => { options.onError?.(error); throw error } })
+  try {
+    return await readHistory({ filter, relays: options.relays, receiverPubkey: options.receiverPubkey, signal: options.signal, getEvents: _getEvents, processEvent: processOuterEvent, acquirePage: _acquirePage })
+  } 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, 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')

package/private-messenger/helpers/publication.js

@@ -1,7 +1,8 @@
 import { getEventHash } from '../../event/index.js'
 
 // A report describes one outer event, not one relay. Each outer event needs
-// at least one relay acknowledgement. Keep the successful fast path immediate.
+// accepted publication covering its routed recipients. Keep the successful fast
+// path immediate; a partially covered multi-recipient report remains a failure.
 export async function assertMessagePublished (result, event) {
   const reports = result?.delivery?.reports
   const present = Array.isArray(reports) && reports.length > 0

package/private-messenger/helpers/send-routing.js

@@ -1,4 +1,5 @@
 import { normalizeRelayUrl } from '../../url/index.js'
+import { ValidationError } from '../../error/index.js'
 
 const REJECTION_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', 'rate-limited', 'error'])
 const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
@@ -14,17 +15,60 @@ export function isReplaceableRelayFailure (error) {
   return REJECTION_PREFIXES.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
 }
 
-export function createSendRelayRouting ({ peer, relaysByPubkey, exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
-  // One finite snapshot, including the existing default pair if NIP-65 is
-  // unavailable. Never invent additional fallback relays.
-  const candidates = [...pickRelays([peer], relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }).keys()]
+export function normalizeFallbackRelays (value = []) {
+  if (!Array.isArray(value)) throw new ValidationError('INVALID_FALLBACK_RELAYS')
+  return [...new Set(Array.from(value, normalizeRelayUrl))]
+}
+
+function routeEntries (routes) {
+  return routes instanceof Map ? [...routes] : Object.entries(routes || {})
+}
+
+function routeGroups (routes) {
+  const groups = new Map()
+  for (const [relay, receivers] of routes) {
+    const key = [...receivers].sort().join(',')
+    if (!groups.has(key)) groups.set(key, { receivers, relays: [] })
+    groups.get(key).relays.push(relay)
+  }
+  return [...groups.values()]
+}
+
+export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey, primaryRelays, primaryRelayToReceivers, fallbackRelays = [], exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
+  // Keep discovery's defaults when NIP-65 is unavailable. Explicit maps/lists
+  // retain their fanout; configured fallbacks are a separate last-resort stage.
+  const explicit = Boolean(primaryRelays || primaryRelayToReceivers)
+  const primaryRoutes = primaryRelayToReceivers || (primaryRelays
+    ? new Map(primaryRelays.map(relay => [relay, peers]))
+    : pickRelays(peers, relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }))
+  const primaryByPeer = Object.fromEntries(peers.map(pubkey => [pubkey, { read: [] }]))
+  for (const [relay, receivers] of routeEntries(primaryRoutes)) {
+    for (const pubkey of Array.isArray(receivers) ? receivers : [receivers]) primaryByPeer[pubkey]?.read.push(normalizeRelayUrl(relay))
+  }
+  const candidates = [...new Set([...Object.values(primaryByPeer).flatMap(value => value.read), ...fallbackRelays])]
   const candidateSet = new Set(candidates)
   for (const [relay, expires] of exclusions) if (expires <= now() || !candidateSet.has(relay)) exclusions.delete(relay)
-  // New attempts may recheck an exhausted list. Each in-flight outer event has
-  // its own tried set, preventing loops during concurrent sends.
-  if (candidates.length && candidates.every(relay => exclusions.has(relay))) exclusions.clear()
-  const select = excluded => pickRelays([peer], relaysByPubkey, { relayType: 'read', excludeRelaysByPubkey: new Map([[peer, [...excluded]]]) })
-  const relayToReceivers = select(exclusions.keys())
+  // A fresh attempt can recheck an exhausted list; each outer event still owns
+  // a tried set so concurrent sends/fragments cannot create a retry loop.
+  if (peers.some(pubkey => {
+    const available = [...primaryByPeer[pubkey].read, ...fallbackRelays]
+    return available.length && available.every(relay => exclusions.has(relay))
+  })) exclusions.clear()
+  const select = (receivers, excluded, staged = false) => {
+    const excludedRelays = [...excluded]
+    const excludeRelaysByPubkey = new Map(receivers.map(pubkey => [pubkey, excludedRelays]))
+    const options = { relayType: 'read', excludeRelaysByPubkey, emptyRelaysFallback: [] }
+    const routes = pickRelays(receivers, primaryByPeer, { ...options, ...(explicit ? { maxPerPubkey: Infinity } : {}) })
+    // For one ciphertext, exhaust the remaining members' primary routes before
+    // using a common fallback. Initial wrapping must nevertheless cover everyone.
+    if (staged && routes.size) return routes
+    const covered = new Set([...routes.values()].flat())
+    const missing = receivers.filter(pubkey => !covered.has(pubkey))
+    const fallback = pickRelays(missing, Object.fromEntries(missing.map(pubkey => [pubkey, { read: fallbackRelays }])), options)
+    for (const [relay, pubkeys] of fallback) routes.set(relay, [...new Set([...(routes.get(relay) || []), ...pubkeys])])
+    return routes
+  }
+  const relayToReceivers = primaryRelayToReceivers || select(peers, exclusions.keys())
   const current = () => !signal?.aborted && isCurrent()
   const rejected = report => (report?.errors || []).filter(item => candidateSet.has(normalized(item.relay)) && isReplaceableRelayFailure(item.reason))
   const remember = errors => { for (const item of errors) exclusions.set(normalized(item.relay), now() + EXCLUSION_MS) }
@@ -33,58 +77,68 @@ export function createSendRelayRouting ({ peer, relaysByPubkey, exclusions, pick
     try { return await isOnline({ signal }) && current() } catch { return false }
   }
 
-  async function send (event, initialRelays) {
+  async function send (event, initialRelays, context = {}) {
+    // This context describes the already encrypted recipient subset. It stays
+    // local: no recipient tags or routing metadata are added to the outer event.
+    const receivers = context.receiverPubkeys || peers
+    const pending = new Set(receivers)
     const mirrors = initialRelays.filter(relay => !candidateSet.has(normalized(relay)))
-    let relays = [...new Set([...select(exclusions.keys()).keys(), ...mirrors])]
+    const initialPrimary = context.primaryRelays || (primaryRelays || peers.length === 1 ? routeEntries(relayToReceivers).map(([relay]) => relay) : [])
+    const first = [...new Set(initialPrimary.map(normalizeRelayUrl))].filter(relay => !exclusions.has(relay))
+    let batch = first.length ? { receivers, relays: first } : null
     const tried = new Set()
     const errors = []
     const summaries = []
-    const finish = result => {
-      if (summaries.length === 1) return result
-      return {
-        ...result,
+    const next = () => routeGroups(select([...pending], new Set([...exclusions.keys(), ...tried]), true))[0]
+    const finish = result => ({
+      ...result,
+      success: summaries.length > 0 && pending.size === 0,
+      total: tried.size,
+      promise: Promise.all(summaries).then(reports => ({
         total: tried.size,
-        promise: Promise.all(summaries).then(reports => ({
-          total: tried.size,
-          success: reports.some(report => report.success),
-          fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
-          succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
-          errors: reports.flatMap(report => report.errors || [])
-        }))
-      }
-    }
-    while (true) {
+        success: summaries.length > 0 && pending.size === 0,
+        fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
+        succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
+        errors: reports.flatMap(report => report.errors || [])
+      }))
+    })
+    let result = { success: false }
+    while ((batch ||= next())) {
       signal?.throwIfAborted()
+      const relays = [...new Set([...batch.relays, ...(summaries.length ? [] : mirrors)])]
       for (const relay of relays) tried.add(normalized(relay))
-      // Republish the exact signed outer event, preserving encryption,
-      // fragments, timestamps and deletion capabilities.
-      const result = await sendEvent(event, relays)
+      // Every relay in this batch serves the same pending recipient subset.
+      // One ACK covers that subset, never unrelated members of the ciphertext.
+      result = await sendEvent(event, relays)
       const settled = Promise.resolve(result.promise)
       summaries.push(settled)
       if (result.success) {
+        for (const pubkey of batch.receivers) pending.delete(pubkey)
         // Keep the first ACK immediate; learn about redundant failures later.
         settled.then(async report => {
           const failed = rejected(report)
           if (failed.length && await online()) remember(failed)
         }).catch(() => {})
-        return finish(result)
+        if (!pending.size) return finish(result)
+      } else {
+        const report = await settled
+        const failed = rejected(report)
+        errors.push(...(report?.errors || []))
+        if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
+        if (!next()) { exclusions.clear(); return finish(result) }
+        if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
+        remember(failed)
       }
-      const report = await settled
-      const failed = rejected(report)
-      errors.push(...(report?.errors || []))
-      if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
-      const next = [...select(new Set([...exclusions.keys(), ...tried])).keys()]
-      if (!next.length) { exclusions.clear(); return finish(result) }
-      if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
-      remember(failed)
-      relays = next
+      if (!current()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: false }
+      batch = null
     }
+    return finish(result)
   }
 
   return {
     relayToReceivers,
-    // A recovery mirror must not reintroduce the recipient's refused relays.
-    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(relay) || !exclusions.has(relay)),
+    // A recovery mirror must not reintroduce refused relays or promote a fallback.
+    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(normalized(relay)) || !exclusions.has(normalized(relay))),
     _publish: options => (options.nymSigner ? publishNymEvent : publish)({ ...options, _publish: send })
   }
 }

package/private-messenger/index.js

@@ -42,9 +42,11 @@
 // - Seeder replies stream compact routers with createMissingMessageReplyPacker({ messenger, question }).update(seed), then finalize(optionalLastSeed).
 // - For other event-list replies, use createEventReplyPacker({ messenger, question, code }).update(event).
 
+import { createAbortableSemaphore } from '../helpers/abortable-semaphore.js'
 import * as privateMessage from '../private-message/index.js'
 import { isOnline } from '../network/index.js'
-import { createSendRelayRouting } from './helpers/send-routing.js'
+import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
+import { normalizeRelayUrl } from '../url/index.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { bytesToBase64 } from '../base64/index.js'
 import { ValidationError } from '../error/index.js'
@@ -193,6 +195,7 @@ export class PrivateMessenger {
   }
 
   constructor ({
+    fallbackRelays = [],
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
     identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
@@ -226,6 +229,7 @@ export class PrivateMessenger {
     _storageClearInterval = globalThis.clearInterval.bind(globalThis),
     _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
+    this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
     this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
@@ -282,6 +286,7 @@ export class PrivateMessenger {
     this.deliveryReads = new Set()
     this.deliveryWaiters = new Set()
     this.recoveries = new Map()
+    this.recoveryAdmission = createAbortableSemaphore(2)
     this.recoveryControllers = new Set()
     this.resumeWork = null
     this.capacityTimer = null
@@ -756,42 +761,38 @@ export class PrivateMessenger {
   }
 
   async resolveWatchRelays (channel) {
-    if (!channel.usesNip65WatchRelays && channel.relays.length) return channel.relays
-    return this.readRelaysForPubkey(this.userPubkey)
+    const primary = !channel.usesNip65WatchRelays && channel.relays.length ? channel.relays : await this.readRelaysForPubkey(this.userPubkey)
+    return uniq([...primary, ...this.fallbackRelays].map(normalizeRelayUrl))
   }
 
   async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers, signal }) {
     const recoveryRelays = await this.recoveryMirrorRelays(channel.pubkey)
-    if (relayToReceivers) return { relayToReceivers, recoveryRelays }
-    if (relays?.length) return { relays: uniq(relays), recoveryRelays }
-    if (channel.sendRelays.length) return { relays: channel.sendRelays, recoveryRelays }
-    if (channel.relays.length) return { relays: channel.relays, recoveryRelays }
-    const recipients = uniq(receiverPubkeys)
-    if (recipients.length === 1) {
-      const peer = recipients[0]
-      const relaysByPubkey = await this._getRelaysByPubkey(recipients)
-      const key = `${channel.pubkey}:${peer}`
-      if (!this.sendRelayExclusions.has(key)) {
-        if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
-        this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
-      }
-      const routing = createSendRelayRouting({
-        peer, relaysByPubkey, recoveryRelays,
-        signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
-        exclusions: this.sendRelayExclusions.get(key).exclusions,
-        pickRelays: this._pickRelaysForPubkeys,
-        publish: this._privateChannel.publish || privateChannel.publish,
-        publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
-        sendEvent: (...args) => relayPool.sendEvent(...args),
-        isOnline: this._isOnline,
-        isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
-      })
-      if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
-      return routing
+    if (relayToReceivers && !this.fallbackRelays.length) return { relayToReceivers, recoveryRelays }
+    const fixed = relayToReceivers ? null : relays?.length ? uniq(relays) : channel.sendRelays.length ? channel.sendRelays : channel.relays.length ? channel.relays : null
+    if (fixed && !this.fallbackRelays.length) return { relays: fixed, recoveryRelays }
+    const recipients = uniq(receiverPubkeys?.length ? receiverPubkeys : relayMapReceivers(relayToReceivers))
+    const relaysByPubkey = fixed || relayToReceivers ? undefined : await this._getRelaysByPubkey(recipients)
+    const key = `${channel.pubkey}:${[...recipients].sort().join(',')}`
+    if (!this.sendRelayExclusions.has(key)) {
+      if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
+      this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
     }
-    const derived = await this.readRelayToReceivers(recipients)
-    if (!relayMapRelays(derived).length) throw new ValidationError('NO_RELAYS')
-    return { relayToReceivers: derived, recoveryRelays }
+    const routing = createSendRelayRouting({
+      peers: fixed && !recipients.length ? [this.userPubkey] : recipients, relaysByPubkey, recoveryRelays, primaryRelays: fixed?.map(normalizeRelayUrl), primaryRelayToReceivers: relayToReceivers, fallbackRelays: this.fallbackRelays,
+      signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
+      exclusions: this.sendRelayExclusions.get(key).exclusions,
+      pickRelays: this._pickRelaysForPubkeys,
+      publish: this._privateChannel.publish || privateChannel.publish,
+      publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
+      sendEvent: (...args) => relayPool.sendEvent(...args),
+      isOnline: this._isOnline,
+      isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
+    })
+    if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
+    // Fixed lists address the original receiver set as a whole, preserving the
+    // existing encryption grouping instead of inventing per-recipient routes.
+    if (fixed) return { relays: fixed, recoveryRelays: routing.recoveryRelays, _publish: routing._publish }
+    return routing
   }
 
   readState () {
@@ -1951,12 +1952,11 @@ export class PrivateMessenger {
   }
 
   async askSeedersForRelayLeftEdge (channelPubkey, range, fetchedEvents) {
-    const { asks } = await this.#askSeedersForRelayLeftEdgeAttempt(channelPubkey, range, fetchedEvents)
+    const { asks } = await this.#askSeedersForRelayLeftEdgeAttempt(channelPubkey, range, oldestCreatedAt(fetchedEvents))
     return asks
   }
 
-  async #askSeedersForRelayLeftEdgeAttempt (channelPubkey, range, fetchedEvents) {
-    const oldest = oldestCreatedAt(fetchedEvents)
+  async #askSeedersForRelayLeftEdgeAttempt (channelPubkey, range, oldest) {
     const until = oldest == null ? range.end : Math.min(range.end, oldest)
     if (until < range.start) return { asks: [], failures: [] }
     return this.#askSeedersForMissingRangeAttempt(channelPubkey, range.start, until)
@@ -2099,7 +2099,8 @@ export class PrivateMessenger {
           if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) throw new Error('PRIVATE_MESSENGER_PAUSED')
           const fetchRelays = await this.resolveWatchRelays(channel)
           controller.signal.throwIfAborted()
-          const fetchedEvents = await this._privateChannel.fetch({
+          const history = await this._privateChannel.fetchHistory({
+            _acquirePage: signal => this.recoveryAdmission.acquire(signal),
             signal: controller.signal,
             receivedChunkScope: this.storageLeaseId,
             receiverSigner: this.userSigner,
@@ -2121,9 +2122,9 @@ export class PrivateMessenger {
             onSeedEvent: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
             onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
             onError: err => { throw err }
-          }) || []
+          })
           controller.signal.throwIfAborted()
-          const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, fetchedEvents)
+          const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, history.oldestCreatedAt)
           const lifecycleChanged = this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
             (this.watchRevisionByChannel.get(pubkey) || 0) !== watchRevision
           if (lifecycleChanged || attempt.failures.length) remaining.push(range)
@@ -2330,6 +2331,12 @@ function oldestCreatedAt (events) {
   return oldest
 }
 
+function relayMapReceivers (relayToReceivers) {
+  if (!relayToReceivers) return []
+  const values = relayToReceivers instanceof Map ? [...relayToReceivers.values()] : Object.values(relayToReceivers)
+  return uniq(values.flat())
+}
+
 function relayMapRelays (relayToReceivers) {
   if (!relayToReceivers) return []
   const entries = relayToReceivers instanceof Map ? relayToReceivers.entries() : Object.entries(relayToReceivers)

package/private-messenger/session/README.md

@@ -48,21 +48,53 @@ This is a DM profile; group membership/key derivation is not implemented.
 
 ## Relay fallback
 
-Automatic single-recipient routing uses the recipient's NIP-65 read relays, at
-most two per attempt. On `blocked`, `restricted`, `auth-required`, `pow`,
-`rate-limited`, or `error` rejections, or connection/transport/timeout failures,
-it can try remaining read relays after `isOnline` confirms connectivity. Invalid
-messages, local signer/authentication failures and unknown error text retain their
-original diagnosis. Explicit per-call `relays`/`relayToReceivers`, channel
-`sendRelays`/`relays`, and multi-recipient sends do not enable automatic fallback.
+Both `createPrivateMessenger` and `createPrivateMessageSession` accept an optional
+`fallbackRelays` array (default `[]`) at construction. URLs are normalized,
+deduplicated and copied; invalid values throw `ValidationError`. For example:
+
+```js
+const session = createPrivateMessageSession({
+  owner, signer, eventStore,
+  fallbackRelays: ['wss://relay.44billion.net']
+})
+```
+
+Automatic sends try each recipient's NIP-65 read relays first, at most two per
+recipient per attempt, then the configured fallbacks in pairs. Explicit
+per-call `relays`, channel `sendRelays`/`relays` and global `relays` remain primary
+and also support configured fallbacks, including fixed multi-recipient sends.
+Explicit lists retain their requested initial fanout; no recipient relay lookup
+is added. A relay present in both lists is attempted only once per outer event.
+Automatic multi-recipient sends and explicit `relayToReceivers` maps also support
+fallbacks. Explicit maps retain their precedence over fixed lists, initial fanout
+and encrypted recipient subsets, without consulting recipient NIP-65 lists.
+The session coordinator remains a DM API; multi-recipient channels use
+`createPrivateMessenger` directly.
+
+On `blocked`, `restricted`, `auth-required`, `pow`, `rate-limited`, or `error`
+rejections, or connection/transport/timeout failures, replacement requires
+`isOnline` to confirm connectivity. Invalid messages, local signer/authentication
+failures and unknown error text retain their original diagnosis.
+
+Receive routing always adds the configured fallback relays to the effective
+primary list (explicit `relays` or the owner's NIP-65 read relays). Listen there
+from the start, even when primary relays are healthy: a sender may have used a
+fallback after publication was refused elsewhere. Live watches, historical
+recovery and file-channel reads share this policy. NIP-65 refreshes retain the
+fallbacks; outgoing exclusions never remove them from receive subscriptions.
+No public recipient tags or changes to a user's NIP-65 event are introduced.
 
 Each signed outer event is reused verbatim, including router/carrier fragments
 and deletion capabilities. Native errors from exhausted attempts remain in its
-publication report. One successful relay acknowledgement completes that outer
-event immediately; other acknowledgements may update future routing preferences
-without delaying the send. Preferences are channel/recipient-scoped, in-memory,
+publication report. A shared relay's first ACK covers all members assigned to
+that publication batch. If replacements use different relays for different
+members, every pending member must be covered before the outer event succeeds;
+a partial ACK cannot hide another member's failure. Remaining primary routes are
+exhausted before configured fallbacks. Redundant acknowledgements may update
+future routing preferences without delaying a successfully covered send. Preferences are channel/recipient-scoped, in-memory,
 expire after five minutes, and never alter receive subscriptions. A fresh attempt
-can recheck an exhausted list. No additional public fallback relays are invented.
+can recheck an exhausted list. Additional fallback relays come only from the
+caller configuration; absent NIP-65 lists retain the existing discovery defaults.
 
 When offline/interrupted with alternatives remaining, reports carry
 `retryWhenAvailable: true`. The outbox remains pending and emits no `onSendError`.

package/private-messenger/session/index.js

@@ -8,6 +8,7 @@ import { decodeFileMetadata } from '../../nip94/index.js'
 import { createChatOutbox } from './helpers/work-storage.js'
 import { messengerSigner } from './helpers/signer.js'
 import { assertMessagePublished } from '../helpers/publication.js'
+import { normalizeFallbackRelays } from '../helpers/send-routing.js'
 
 export function wireEvent (value, owner) {
   const event = { kind: value.kind, created_at: value.created_at, tags: structuredClone(value.tags), content: value.content, pubkey: value.pubkey || owner }
@@ -17,7 +18,8 @@ export function wireEvent (value, owner) {
 // Relay rejection text must not be interpreted as a local signer denial.
 const retryable = error => error?.code === 'MESSAGE_NOT_PUBLISHED' || !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|BLOCKED|EXPIRED|NOT_IN_PERSONA/i.test(`${error?.code || ''} ${error?.message || ''}`)
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+  fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   const userSigner = messengerSigner(signer)
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
@@ -74,7 +76,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (closed || !available || version !== lifecycle) return
       values.push(channel)
     }
-    if (!messenger) messenger = await Messenger({ seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
+    if (!messenger) messenger = await Messenger({ fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
     if (closed || !available || version !== lifecycle) { await messenger.pause('signer'); return }
     await messenger.update({ channels: values })
     await messenger.resume('signer')