@zervonex/baileys 3.0.1 → 3.0.3

package/lib/Socket/messages-recv.js

@@ -1,904 +1,981 @@
-import NodeCache from '@cacheable/node-cache'
-import { Boom } from '@hapi/boom'
-import { randomBytes } from 'crypto'
-import { proto } from '../../WAProto/index.js'
-import { DEFAULT_CACHE_TTLS, KEY_BUNDLE_TYPE, MIN_PREKEY_COUNT, PLACEHOLDER_MAX_AGE_SECONDS, STATUS_EXPIRY_SECONDS } from '../Defaults/index.js'
-import { WAMessageStatus, WAMessageStubType } from '../Types/index.js'
-import {
-  aesDecryptCTR, aesEncryptGCM, cleanMessage, Curve, decodeMediaRetryNode,
-  decodeMessageNode, makeMutex, decryptMessageNode, delay, derivePairingCodeKey,
-  encodeBigEndian, encodeSignedDeviceIdentity, extractAddressingContext,
-  extractE2ESessionFromRetryReceipt, getCallStatusFromNode, getHistoryMsg,
-  getNextPreKeys, getStatusFromReceiptType, extractMessageText,
-  handleIdentityChange, hkdf, MISSING_KEYS_ERROR_TEXT, NACK_REASONS,
-  NO_MESSAGE_FOUND_ERROR_TEXT, SERVER_ERROR_CODES, toNumber, unixTimestampSeconds,
-  xmppPreKey, xmppSignedPreKey, ACCOUNT_RESTRICTED_TEXT, buildMergedTcTokenIndexWrite,
-  isTcTokenExpired, readTcTokenIndex, resolveTcTokenJid, resolveIssuanceJid,
-  storeTcTokensFromIqResult, TC_TOKEN_INDEX_KEY, decryptMsmsgBotMessage,
-  decodeDecryptedMsmsgMessage, extractReportingInfoFromStanza, getContentType,
-} from '../Utils/index.js'
-import {
-  areJidsSameUser, binaryNodeToString, getAllBinaryNodeChildren, getBinaryNodeChild,
-  getBinaryNodeChildBuffer, getBinaryNodeChildren, getBinaryNodeChildString,
-  getBinaryNodeChildUInt, isJidGroup, isJidNewsletter, isJidStatusBroadcast,
-  isLidUser, isPnUser, jidDecode, jidNormalizedUser, S_WHATSAPP_NET, jidEncode,
-} from '../WABinary/index.js'
-import { extractGroupMetadata } from './groups.js'
-import { makeMessagesSocket } from './messages-send.js'
-
-// ─── Pure stanza builders ─────────────────────────────────────────────────────
-
-export const buildGroupCallStanza = ({ id, to, callId, callCreator, offerContent }) => ({
-  tag: 'call',
-  attrs: { id, to },
-  content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': callCreator, type: 'group', 'group-jid': to }, content: offerContent }]
-})
-
-export const buildGroupCallCancelStanza = ({ to, callId, callCreator }) => ({
-  tag: 'call',
-  attrs: { from: callCreator, to },
-  content: [{ tag: 'terminate', attrs: { 'call-id': callId, 'call-creator': callCreator, reason: 'user-terminated', count: '0' }, content: undefined }]
-})
-
-// ─── Socket ───────────────────────────────────────────────────────────────────
-
-export const makeMessagesRecvSocket = (config) => {
-  const { logger, retryRequestDelayMs, maxMsgRetryCount, getMessage, shouldIgnoreJid, enableAutoSessionRecreation } = config
-  const sock = makeMessagesSocket(config)
-  const { ev, authState, ws, processingMutex, signalRepository, query, upsertMessage, resyncAppState, onUnexpectedError, assertSessions, sendNode, relayMessage, sendReceipt, uploadPreKeys, sendPeerDataOperationMessage, messageRetryManager, registerSocketEndHandler, issuePrivacyTokens, fetchAccountReachoutTimelock, placeholderResendCache: sockPlaceholderResendCache } = sock
-
-  const getLIDForPN = signalRepository.lidMapping.getLIDForPN.bind(signalRepository.lidMapping)
-  const { messageMutex, notificationMutex, receiptMutex: _receiptMutex, placeholderResendCache } = sock
-  const retryMutex = makeMutex()
-  const msgRetryCache = config.msgRetryCounterCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.MSG_RETRY, useClones: false })
-  const callOfferCache = config.callOfferCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.CALL_OFFER, useClones: false })
-  const identityAssertDebounce = new NodeCache({ stdTTL: 5, useClones: false })
-  const inFlightPreKeyLow = new Set()
-  const inFlight463Recoveries = new Set()
-
-  let sendActiveReceipts = false
-
-  // ── PDO helpers ───────────────────────────────────────────────────────────
-
-  const fetchMessageHistory = async (count, oldestMsgKey, oldestMsgTimestamp) => {
-    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
-    return sendPeerDataOperationMessage({ historySyncOnDemandRequest: { chatJid: oldestMsgKey.remoteJid, oldestMsgFromMe: oldestMsgKey.fromMe, oldestMsgId: oldestMsgKey.id, oldestMsgTimestampMs: oldestMsgTimestamp, onDemandMsgCount: count }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND })
-  }
-
-  const requestPlaceholderResend = async (messageKey, msgData) => {
-    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
-    if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'already requested resend'); return }
-    await placeholderResendCache.set(messageKey?.id, msgData || true)
-    await delay(2000)
-    if (!(await placeholderResendCache.get(messageKey?.id))) { logger.debug({ messageKey }, 'message received while resend requested'); return 'RESOLVED' }
-    setTimeout(async () => { if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'PDO message without response after 8 seconds. Phone possibly offline'); await placeholderResendCache.del(messageKey?.id) } }, 8000)
-    return sendPeerDataOperationMessage({ placeholderMessageResendRequest: [{ messageKey }], peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.PLACEHOLDER_MESSAGE_RESEND })
-  }
-
-  const requestContactRefresh = async (jids) => {
-    if (!jids?.length) return
-    return sendPeerDataOperationMessage({ contactRefreshRequest: { jids: Array.isArray(jids) ? jids : [jids] }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.CONTACT_REFRESH_REQUEST })
-  }
-
-  // ── Newsletter notifications ──────────────────────────────────────────────
-
-  const handleMexNewsletterNotification = async (node) => {
-    const mexNode = getBinaryNodeChild(node, 'mex')
-    if (!mexNode?.content) return
-    let data
-    try { data = JSON.parse(mexNode.content.toString()) } catch { return }
-    const { operation, updates } = data || {}
-    if (!updates || !operation) return
-    logger.info({ operation, updates }, 'got mex newsletter notification')
-    switch (operation) {
-      case 'NotificationNewsletterUpdate':
-        for (const update of updates) if (update.jid && update.settings && Object.keys(update.settings).length > 0) ev.emit('newsletter-settings.update', { id: update.jid, update: update.settings })
-        break
-      case 'NotificationNewsletterAdminPromote':
-        for (const update of updates) if (update.jid && update.user) ev.emit('newsletter-participants.update', { id: update.jid, author: node.attrs.from, user: update.user, new_role: 'ADMIN', action: 'promote' })
-        break
-      default:
-        logger.info({ operation, data }, 'Unhandled mex newsletter notification')
-    }
-  }
-
-  const handleNewsletterNotification = async (node) => {
-    const from = node.attrs.from
-    const child = getAllBinaryNodeChildren(node)[0]
-    const author = node.attrs.participant
-    logger.info({ from, child }, 'got newsletter notification')
-    switch (child.tag) {
-      case 'reaction':
-        ev.emit('newsletter.reaction', { id: from, server_id: child.attrs.message_id, reaction: { code: getBinaryNodeChildString(child, 'reaction'), count: 1 } })
-        break
-      case 'view':
-        ev.emit('newsletter.view', { id: from, server_id: child.attrs.message_id, count: parseInt(child.content?.toString() || '0', 10) })
-        break
-      case 'participant':
-        ev.emit('newsletter-participants.update', { id: from, author, user: child.attrs.jid, action: child.attrs.action, new_role: child.attrs.role })
-        break
-      case 'update':
-        const settingsNode = getBinaryNodeChild(child, 'settings')
-        if (settingsNode) {
-          const update = {}
-          const nameNode = getBinaryNodeChild(settingsNode, 'name')
-          if (nameNode?.content) update.name = nameNode.content.toString()
-          const descNode = getBinaryNodeChild(settingsNode, 'description')
-          if (descNode?.content) update.description = descNode.content.toString()
-          ev.emit('newsletter-settings.update', { id: from, update })
-        }
-        break
-      case 'message':
-        const plaintextNode = getBinaryNodeChild(child, 'plaintext')
-        if (plaintextNode?.content) {
-          try {
-            const buf = typeof plaintextNode.content === 'string' ? Buffer.from(plaintextNode.content, 'binary') : Buffer.from(plaintextNode.content)
-            const messageProto = proto.Message.decode(buf).toJSON()
-            const fullMessage = proto.WebMessageInfo.fromObject({ key: { remoteJid: from, id: child.attrs.message_id || child.attrs.server_id, fromMe: false }, message: messageProto, messageTimestamp: +child.attrs.t }).toJSON()
-            await upsertMessage(fullMessage, 'append')
-          } catch (error) { logger.error({ error }, 'Failed to decode plaintext newsletter message') }
-        }
-        break
-      default:
-        logger.warn({ node }, 'Unknown newsletter notification')
-    }
-  }
-
-  // ── ACK / call helpers ────────────────────────────────────────────────────
-
-  const sendMessageAck = async (node, errorCode) => {
-    const { tag, attrs, content } = node
-    const hasUnavailable = !!getBinaryNodeChild({ tag, attrs, content }, 'unavailable')
-    const stanza = { tag: 'ack', attrs: { id: attrs.id, to: attrs.from, class: tag } }
-    if (errorCode) stanza.attrs.error = errorCode.toString()
-    if (attrs.participant) stanza.attrs.participant = attrs.participant
-    if (attrs.recipient) stanza.attrs.recipient = attrs.recipient
-    if (attrs.type || hasUnavailable || errorCode) stanza.attrs.type = attrs.type
-    if (tag === 'message' && authState.creds.me?.id) stanza.attrs.from = authState.creds.me.id
-    logger.debug({ recv: { tag, attrs }, sent: stanza.attrs }, 'sent ack')
-    try { await sendNode(stanza) } catch (error) {
-      if (error?.output?.statusCode === 428 || error?.message?.includes('Connection')) logger.warn({ id: attrs.id, error: error?.message }, 'Failed to send ACK (connection closed) - message already received')
-      else throw error
-    }
-  }
-
-  const rejectCall = async (callId, callFrom) => {
-    await query({ tag: 'call', attrs: { from: authState.creds.me.id, to: callFrom }, content: [{ tag: 'reject', attrs: { 'call-id': callId, 'call-creator': callFrom, count: '0' }, content: undefined }] })
-  }
-
-  const offerCall = async (toJid, isVideo = false) => {
-    const callId = randomBytes(16).toString('hex').toUpperCase().substring(0, 64)
-    const offerContent = []
-    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '16000' }, content: undefined })
-    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '8000' }, content: undefined })
-    if (isVideo) offerContent.push({ tag: 'video', attrs: { orientation: '0', screen_width: '1920', screen_height: '1080', device_orientation: '0', enc: 'vp8', dec: 'vp8' } })
-    offerContent.push({ tag: 'net', attrs: { medium: '3' }, content: undefined })
-    offerContent.push({ tag: 'capability', attrs: { ver: '1' }, content: new Uint8Array([1, 4, 255, 131, 207, 4]) })
-    offerContent.push({ tag: 'encopt', attrs: { keygen: '2' }, content: undefined })
-    const encKey = randomBytes(32)
-    const devices = (await getUSyncDevices([toJid], true, false)).map(({ user, device }) => jidEncode(user, 's.whatsapp.net', device))
-    await assertSessions(devices, true)
-    const { nodes: destinations, shouldIncludeDeviceIdentity } = await createParticipantNodes(devices, { call: { callKey: encKey } }, {})
-    offerContent.push({ tag: 'destination', attrs: {}, content: destinations })
-    if (shouldIncludeDeviceIdentity) offerContent.push({ tag: 'device-identity', attrs: {}, content: encodeSignedDeviceIdentity(authState.creds.account, true) })
-    await query({ tag: 'call', attrs: { to: toJid }, content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': authState.creds.me.id }, content: offerContent }] })
-    return { callId, toJid, isVideo }
-  }
-
-  // ── Retry logic ───────────────────────────────────────────────────────────
-
-  const sendRetryRequest = async (node, forceIncludeKeys = false) => {
-    const { fullMessage } = decodeMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '')
-    const { key: msgKey } = fullMessage
-    const msgId = msgKey.id
-
-    if (messageRetryManager) {
-      if (messageRetryManager.hasExceededMaxRetries(msgId)) { logger.debug({ msgId }, 'reached retry limit with new retry manager, clearing'); messageRetryManager.markRetryFailed(msgId); return }
-      const retryCount = messageRetryManager.incrementRetryCount(msgId)
-      await msgRetryCache.set(`${msgId}:${msgKey?.participant}`, retryCount)
-    } else {
-      const key = `${msgId}:${msgKey?.participant}`
-      let retryCount = (await msgRetryCache.get(key)) || 0
-      if (retryCount >= maxMsgRetryCount) { logger.debug({ retryCount, msgId }, 'reached retry limit, clearing'); await msgRetryCache.del(key); return }
-      await msgRetryCache.set(key, retryCount + 1)
-    }
-
-    const retryCount = (await msgRetryCache.get(`${msgId}:${msgKey?.participant}`)) || 1
-    const { account, signedPreKey, signedIdentityKey: identityKey } = authState.creds
-    const fromJid = node.attrs.from
-    let shouldRecreateSession = false, recreateReason = ''
-
-    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1) {
-      try {
-        const sessionId = signalRepository.jidToSignalProtocolAddress(fromJid)
-        const hasSession = await signalRepository.validateSession(fromJid)
-        let lidJid = null
-        if (isPnUser(fromJid)) lidJid = await signalRepository.lidMapping.getLIDForPN(fromJid)
-        const result = messageRetryManager.shouldRecreateSession(fromJid, retryCount, hasSession.exists)
-        shouldRecreateSession = result.recreate; recreateReason = result.reason
-        if (shouldRecreateSession) {
-          logger.debug({ fromJid, lidJid, retryCount, reason: recreateReason }, 'recreating session for retry')
-          await authState.keys.set({ session: { [sessionId]: null } })
-          if (lidJid) await authState.keys.set({ session: { [signalRepository.jidToSignalProtocolAddress(lidJid)]: null } })
-          forceIncludeKeys = true
-        }
-      } catch (error) { logger.warn({ error, fromJid }, 'failed to check session recreation') }
-    }
-
-    if (retryCount <= 2) {
-      if (messageRetryManager) {
-        messageRetryManager.schedulePhoneRequest(msgId, async () => {
-          try { const requestId = await requestPlaceholderResend(msgKey); logger.debug(`sendRetryRequest: requested placeholder resend (${requestId}) for message ${msgId} (scheduled)`) }
-          catch (error) { logger.warn({ error, msgId }, 'failed to send scheduled phone request') }
-        })
-      } else {
-        const id = await requestPlaceholderResend(msgKey)
-        logger.debug(`sendRetryRequest: requested placeholder resend for message ${id}`)
-      }
-    }
-
-    const deviceIdentity = encodeSignedDeviceIdentity(account, true)
-    await authState.keys.transaction(async () => {
-      const receipt = { tag: 'receipt', attrs: { id: msgId, type: 'retry', to: node.attrs.from }, content: [{ tag: 'retry', attrs: { count: retryCount.toString(), id: node.attrs.id, t: node.attrs.t, v: '1', error: '0' } }, { tag: 'registration', attrs: {}, content: encodeBigEndian(authState.creds.registrationId) }] }
-      if (node.attrs.recipient) receipt.attrs.recipient = node.attrs.recipient
-      if (node.attrs.participant) receipt.attrs.participant = node.attrs.participant
-      if (retryCount > 1 || forceIncludeKeys || shouldRecreateSession) {
-        const { update, preKeys } = await getNextPreKeys(authState, 1)
-        const [keyId] = Object.keys(preKeys)
-        const key = preKeys[+keyId]
-        receipt.content.push({ tag: 'keys', attrs: {}, content: [{ tag: 'type', attrs: {}, content: Buffer.from(KEY_BUNDLE_TYPE) }, { tag: 'identity', attrs: {}, content: identityKey.public }, xmppPreKey(key, +keyId), xmppSignedPreKey(signedPreKey), { tag: 'device-identity', attrs: {}, content: deviceIdentity }] })
-        ev.emit('creds.update', update)
-      }
-      await sendNode(receipt)
-      logger.info({ msgAttrs: node.attrs, retryCount }, 'sent retry receipt')
-    }, authState?.creds?.me?.id || 'sendRetryRequest')
-  }
-
-  // ── TC token helpers ──────────────────────────────────────────────────────
-
-  const reissueTcTokenAfterIdentityChange = (from) => {
-    void (async () => {
-      const normalizedJid = jidNormalizedUser(from)
-      const tcJid = await resolveTcTokenJid(normalizedJid, getLIDForPN)
-      const tcTokenData = await authState.keys.get('tctoken', [tcJid])
-      const senderTs = tcTokenData?.[tcJid]?.senderTimestamp
-      if (senderTs === null || senderTs === undefined || isTcTokenExpired(senderTs)) return
-      logger.debug({ jid: normalizedJid, senderTimestamp: senderTs }, 'identity changed, re-issuing tctoken')
-      const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
-      const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
-      const issueJid = await resolveIssuanceJid(normalizedJid, issueToLid, getLIDForPN, getPNForLID)
-      const result = await issuePrivacyTokens([issueJid], senderTs)
-      await storeTcTokensFromIqResult({ result, fallbackJid: tcJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
-    })().catch(err => logger.debug({ jid: from, err: err?.message }, 'failed to re-issue tctoken after identity change'))
-  }
-
-  const handlePrivacyTokenNotification = async (node) => {
-    const tokensNode = getBinaryNodeChild(node, 'tokens')
-    if (!tokensNode) return
-    const from = jidNormalizedUser(node.attrs.from)
-    const senderLid = node.attrs.sender_lid && isLidUser(jidNormalizedUser(node.attrs.sender_lid)) ? jidNormalizedUser(node.attrs.sender_lid) : undefined
-    const fallbackJid = senderLid ?? (await resolveTcTokenJid(from, getLIDForPN))
-    logger.debug({ from, storageJid: fallbackJid }, 'processing privacy token notification')
-    await storeTcTokensFromIqResult({ result: node, fallbackJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
-  }
-
-  const tcTokenKnownJids = new Set()
-  const tcTokenIndexLoaded = (async () => {
-    try { const jids = await readTcTokenIndex(authState.keys); for (const jid of jids) tcTokenKnownJids.add(jid); if (tcTokenKnownJids.size > 0) logger.debug({ count: tcTokenKnownJids.size }, 'loaded tctoken index') }
-    catch (err) { logger.warn({ err: err?.message }, 'failed to load tctoken index') }
-  })()
-
-  let tcTokenIndexTimer
-  const flushTcTokenIndex = async () => {
-    if (tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined }
-    const write = await buildMergedTcTokenIndexWrite(authState.keys, tcTokenKnownJids)
-    return authState.keys.set({ tctoken: write })
-  }
-  const scheduleTcTokenIndexSave = () => {
-    if (tcTokenIndexTimer) clearTimeout(tcTokenIndexTimer)
-    tcTokenIndexTimer = setTimeout(() => { tcTokenIndexTimer = undefined; flushTcTokenIndex().catch(err => logger.warn({ err: err?.message }, 'failed to save tctoken index')) }, 5000)
-  }
-  const trackTcTokenJid = (jid) => { if (jid && jid !== TC_TOKEN_INDEX_KEY && !tcTokenKnownJids.has(jid)) { tcTokenKnownJids.add(jid); scheduleTcTokenIndexSave() } }
-
-  // ── Encrypt notification ──────────────────────────────────────────────────
-
-  const handleEncryptNotification = async (node) => {
-    const from = node.attrs.from
-    if (from === S_WHATSAPP_NET) {
-      const stanzaId = node.attrs.id
-      if (stanzaId && inFlightPreKeyLow.has(stanzaId)) return
-      const count = +getBinaryNodeChild(node, 'count').attrs.value
-      logger.debug({ count, shouldUploadMorePreKeys: count < MIN_PREKEY_COUNT }, 'recv pre-key count')
-      if (count < MIN_PREKEY_COUNT) {
-        if (stanzaId) inFlightPreKeyLow.add(stanzaId)
-        try { await uploadPreKeys() } finally { if (stanzaId) inFlightPreKeyLow.delete(stanzaId) }
-      }
-    } else {
-      const result = await handleIdentityChange(node, { meId: authState.creds.me?.id, meLid: authState.creds.me?.lid, validateSession: signalRepository.validateSession, assertSessions, debounceCache: identityAssertDebounce, logger, onBeforeSessionRefresh: reissueTcTokenAfterIdentityChange })
-      if (result.action === 'no_identity_node') logger.info({ node }, 'unknown encrypt notification')
-    }
-  }
-
-  // ── Group notification ────────────────────────────────────────────────────
-
-  const handleGroupNotification = (fullNode, child, msg) => {
-    const actingParticipantLid = fullNode.attrs.participant
-    const actingParticipantPn = fullNode.attrs.participant_pn
-    const affectedParticipantLid = getBinaryNodeChild(child, 'participant')?.attrs?.jid || actingParticipantLid
-    const affectedParticipantPn = getBinaryNodeChild(child, 'participant')?.attrs?.phone_number || actingParticipantPn
-    switch (child?.tag) {
-      case 'create':
-        const metadata = extractGroupMetadata(child)
-        msg.messageStubType = WAMessageStubType.GROUP_CREATE
-        msg.messageStubParameters = [metadata.subject]
-        msg.key = { participant: metadata.owner, participantAlt: metadata.ownerPn }
-        ev.emit('chats.upsert', [{ id: metadata.id, name: metadata.subject, conversationTimestamp: metadata.creation }])
-        ev.emit('groups.upsert', [{ ...metadata, author: actingParticipantLid, authorPn: actingParticipantPn }])
-        break
-      case 'ephemeral':
-      case 'not_ephemeral':
-        msg.message = { protocolMessage: { type: proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING, ephemeralExpiration: +(child.attrs.expiration || 0) } }
-        break
-      case 'modify':
-        const modifiedParticipants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
-        msg.messageStubParameters = modifiedParticipants.map(a => JSON.stringify(a))
-        msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_CHANGE_NUMBER
-        break
-      case 'promote':
-      case 'demote':
-      case 'remove':
-      case 'add':
-      case 'leave':
-        msg.messageStubType = WAMessageStubType[`GROUP_PARTICIPANT_${child.tag.toUpperCase()}`]
-        const participants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isLidUser(attrs.jid) && isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isPnUser(attrs.jid) && isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
-        if (participants.length === 1 && (areJidsSameUser(participants[0].id, actingParticipantLid) || areJidsSameUser(participants[0].id, actingParticipantPn)) && child.tag === 'remove') msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_LEAVE
-        msg.messageStubParameters = participants.map(a => JSON.stringify(a))
-        break
-      case 'subject':
-        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_SUBJECT
-        msg.messageStubParameters = [child.attrs.subject]
-        break
-      case 'description':
-        const description = getBinaryNodeChild(child, 'body')?.content?.toString()
-        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_DESCRIPTION
-        msg.messageStubParameters = description ? [description] : undefined
-        break
-      case 'announcement':
-      case 'not_announcement':
-        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_ANNOUNCE
-        msg.messageStubParameters = [child.tag === 'announcement' ? 'on' : 'off']
-        break
-      case 'locked':
-      case 'unlocked':
-        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_RESTRICT
-        msg.messageStubParameters = [child.tag === 'locked' ? 'on' : 'off']
-        break
-      case 'invite':
-        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_INVITE_LINK
-        msg.messageStubParameters = [child.attrs.code]
-        break
-      case 'member_add_mode':
-        const addMode = child.content
-        if (addMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBER_ADD_MODE; msg.messageStubParameters = [addMode.toString()] }
-        break
-      case 'membership_approval_mode':
-        const approvalMode = getBinaryNodeChild(child, 'group_join')
-        if (approvalMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_MODE; msg.messageStubParameters = [approvalMode.attrs.state] }
-        break
-      case 'created_membership_requests':
-        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
-        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), 'created', child.attrs.request_method]
-        break
-      case 'revoked_membership_requests':
-        const isDenied = areJidsSameUser(affectedParticipantLid, actingParticipantLid)
-        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
-        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), isDenied ? 'revoked' : 'rejected']
-        break
-    }
-  }
-
-  // ── Devices notification ──────────────────────────────────────────────────
-
-  const handleDevicesNotification = async (node) => {
-    const [child] = getAllBinaryNodeChildren(node)
-    const from = jidNormalizedUser(node.attrs.from)
-    if (!child) { logger.debug({ from }, 'devices notification missing child, skipping'); return }
-    const tag = child.tag
-    const deviceHash = child.attrs.device_hash
-    const devices = getBinaryNodeChildren(child, 'device')
-    if (areJidsSameUser(from, authState.creds.me.id) || areJidsSameUser(from, authState.creds.me.lid)) logger.info({ deviceJids: devices.map(d => d.attrs.jid) }, 'got my own devices')
-    if (!devices.length) { logger.debug({ from, tag }, 'no devices in notification, skipping'); return }
-    const decoded = []
-    for (const d of devices) { const jid = d.attrs.jid; if (!jid) continue; const parts = jidDecode(jid); if (!parts) { logger.debug({ jid }, 'failed to decode device jid, skipping'); continue }; decoded.push({ jid, user: parts.user, server: parts.server, device: parts.device }) }
-    if (!decoded.length) return
-    await sock.devicesMutex.mutex(async () => {
-      const byUser = new Map()
-      for (const d of decoded) { const list = byUser.get(d.user) || []; list.push(d); byUser.set(d.user, list) }
-      for (const [user, entries] of byUser) {
-        if (tag === 'update') { logger.debug({ user }, `${user}'s device list updated, dropping cached devices`); await sock.userDevicesCache?.del(user); continue }
-        if (tag === 'remove') await signalRepository.deleteSession(entries.map(e => e.jid))
-        const existingCache = (await sock.userDevicesCache?.get(user)) || []
-        if (!existingCache.length) { logger.debug({ user, tag }, 'device list not cached, deferring to USync refresh'); continue }
-        const affected = new Set(entries.map(e => e.device))
-        let updatedDevices
-        switch (tag) {
-          case 'add': logger.info({ deviceHash, count: entries.length }, 'devices added'); updatedDevices = [...existingCache.filter(d => !affected.has(d.device)), ...entries.map(e => ({ user: e.user, server: e.server, device: e.device }))]; break
-          case 'remove': logger.info({ deviceHash, count: entries.length }, 'devices removed'); updatedDevices = existingCache.filter(d => !affected.has(d.device)); break
-          default: logger.debug({ tag }, 'unknown device list change tag'); continue
-        }
-        if (updatedDevices.length === 0) await sock.userDevicesCache?.del(user)
-        else await sock.userDevicesCache?.set(user, updatedDevices)
-      }
-    })
-  }
-
-  // ── processNotification ───────────────────────────────────────────────────
-
-  const processNotification = async (node) => {
-    const result = {}
-    const [child] = getAllBinaryNodeChildren(node)
-    const nodeType = node.attrs.type
-    const from = jidNormalizedUser(node.attrs.from)
-    switch (nodeType) {
-      case 'privacy_token': await handlePrivacyTokenNotification(node); break
-      case 'newsletter': await handleNewsletterNotification(node); break
-      case 'mex': await handleMexNewsletterNotification(node); break
-      case 'w:gp2': handleGroupNotification(node, child, result); break
-      case 'mediaretry': ev.emit('messages.media-update', [decodeMediaRetryNode(node)]); break
-      case 'encrypt': await handleEncryptNotification(node); break
-      case 'devices':
-        try { await handleDevicesNotification(node) } catch (error) { logger.error({ error, node }, 'failed to handle devices notification') }
-        break
-      case 'server_sync':
-        const update = getBinaryNodeChild(node, 'collection')
-        if (update) await resyncAppState([update.attrs.name], false)
-        break
-      case 'picture':
-        const setPicture = getBinaryNodeChild(node, 'set')
-        const delPicture = getBinaryNodeChild(node, 'delete')
-        ev.emit('contacts.update', [{ id: jidNormalizedUser(node?.attrs?.from) || (setPicture || delPicture)?.attrs?.hash || '', imgUrl: setPicture ? 'changed' : 'removed' }])
-        if (isJidGroup(from)) {
-          const pictureNode = setPicture || delPicture
-          result.messageStubType = WAMessageStubType.GROUP_CHANGE_ICON
-          if (setPicture) result.messageStubParameters = [setPicture.attrs.id]
-          result.participant = pictureNode?.attrs.author
-          result.key = { ...(result.key || {}), participant: setPicture?.attrs.author }
-        }
-        break
-      case 'account_sync':
-        if (child.tag === 'disappearing_mode') {
-          const newDuration = +child.attrs.duration
-          logger.info({ newDuration }, 'updated account disappearing mode')
-          ev.emit('creds.update', { accountSettings: { ...authState.creds.accountSettings, defaultDisappearingMode: { ephemeralExpiration: newDuration, ephemeralSettingTimestamp: +child.attrs.t } } })
-        } else if (child.tag === 'blocklist') {
-          for (const { attrs } of getBinaryNodeChildren(child, 'item')) ev.emit('blocklist.update', { blocklist: [attrs.jid], type: attrs.action === 'block' ? 'add' : 'remove' })
-        }
-        break
-      case 'link_code_companion_reg':
-        const linkCodeNode = getBinaryNodeChild(node, 'link_code_companion_reg')
-        const ref = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_ref'))
-        const primaryIdentityPublicKey = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'primary_identity_pub'))
-        const primaryEphemeralWrapped = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_wrapped_primary_ephemeral_pub'))
-        const codePairingPublicKey = await decipherLinkPublicKey(primaryEphemeralWrapped)
-        const companionSharedKey = Curve.sharedKey(authState.creds.pairingEphemeralKeyPair.private, codePairingPublicKey)
-        const random = randomBytes(32)
-        const linkCodeSalt = randomBytes(32)
-        const linkCodePairingExpanded = hkdf(companionSharedKey, 32, { salt: linkCodeSalt, info: 'link_code_pairing_key_bundle_encryption_key' })
-        const encryptPayload = Buffer.concat([Buffer.from(authState.creds.signedIdentityKey.public), primaryIdentityPublicKey, random])
-        const encryptIv = randomBytes(12)
-        const encrypted = aesEncryptGCM(encryptPayload, linkCodePairingExpanded, encryptIv, Buffer.alloc(0))
-        const encryptedPayload = Buffer.concat([linkCodeSalt, encryptIv, encrypted])
-        const identitySharedKey = Curve.sharedKey(authState.creds.signedIdentityKey.private, primaryIdentityPublicKey)
-        const identityPayload = Buffer.concat([companionSharedKey, identitySharedKey, random])
-        authState.creds.advSecretKey = Buffer.from(hkdf(identityPayload, 32, { info: 'adv_secret' })).toString('base64')
-        await query({ tag: 'iq', attrs: { to: S_WHATSAPP_NET, type: 'set', id: sock.generateMessageTag(), xmlns: 'md' }, content: [{ tag: 'link_code_companion_reg', attrs: { jid: authState.creds.me.id, stage: 'companion_finish' }, content: [{ tag: 'link_code_pairing_wrapped_key_bundle', attrs: {}, content: encryptedPayload }, { tag: 'companion_identity_public', attrs: {}, content: authState.creds.signedIdentityKey.public }, { tag: 'link_code_pairing_ref', attrs: {}, content: ref }] }] })
-        authState.creds.registered = true
-        ev.emit('creds.update', authState.creds)
-        break
-    }
-    if (Object.keys(result).length) return result
-  }
-
-  // ── Link pairing helpers ──────────────────────────────────────────────────
-
-  const decipherLinkPublicKey = async (data) => {
-    const buffer = toRequiredBuffer(data)
-    const salt = buffer.slice(0, 32)
-    const secretKey = await derivePairingCodeKey(authState.creds.pairingCode, salt)
-    const iv = buffer.slice(32, 48)
-    const payload = buffer.slice(48, 80)
-    return aesDecryptCTR(payload, secretKey, iv)
-  }
-
-  const toRequiredBuffer = (data) => {
-    if (data === undefined) throw new Boom('Invalid buffer', { statusCode: 400 })
-    return data instanceof Buffer ? data : Buffer.from(data)
-  }
-
-  // ── Retry helpers ─────────────────────────────────────────────────────────
-
-  const willSendMessageAgain = async (id, participant) => { const retryCount = (await msgRetryCache.get(`${id}:${participant}`)) || 0; return retryCount < maxMsgRetryCount }
-  const updateSendMessageAgainCount = async (id, participant) => { const key = `${id}:${participant}`; await msgRetryCache.set(key, ((await msgRetryCache.get(key)) || 0) + 1) }
-
-  const sendMessagesAgain = async (key, ids, retryNode, receiptNode) => {
-    const remoteJid = key.remoteJid
-    const participant = key.participant || remoteJid
-    const retryCount = +retryNode.attrs.count || 1
-    const msgs = []
-
-    for (const id of ids) {
-      let msg
-      if (messageRetryManager) { const cached = messageRetryManager.getRecentMessage(remoteJid, id); if (cached) { msg = cached.message; logger.debug({ jid: remoteJid, id }, 'found message in retry cache'); messageRetryManager.markRetrySuccess(id) } }
-      if (!msg) { msg = await getMessage({ ...key, id }); if (msg) { logger.debug({ jid: remoteJid, id }, 'found message via getMessage'); if (messageRetryManager) messageRetryManager.markRetrySuccess(id) } }
-      msgs.push(msg)
-    }
-
-    const sendToAll = !jidDecode(participant)?.device
-    const sessionId = signalRepository.jidToSignalProtocolAddress(participant)
-    let injectedFromBundle = false
-    const bundle = extractE2ESessionFromRetryReceipt(receiptNode)
-
-    if (bundle) {
-      try { await signalRepository.injectE2ESession({ jid: participant, session: bundle }); injectedFromBundle = true; logger.debug({ participant, retryCount }, 'injected session from retry receipt key bundle') }
-      catch (error) { logger.warn({ error, participant }, 'failed to inject session from retry receipt') }
-    }
-
-    if (!injectedFromBundle && typeof signalRepository.getSessionInfo === 'function') {
-      const receivedRegId = getBinaryNodeChildUInt(receiptNode, 'registration', 4)
-      if (typeof receivedRegId === 'number' && Number.isInteger(receivedRegId)) {
-        const info = await signalRepository.getSessionInfo(participant)
-        if (info && info.registrationId !== 0 && info.registrationId !== receivedRegId) { logger.info({ participant, stored: info.registrationId, received: receivedRegId }, 'reg id mismatch on retry without bundle, deleting session'); await authState.keys.set({ session: { [sessionId]: null } }) }
-      }
-    }
-
-    if (ids[0] && messageRetryManager && typeof messageRetryManager.saveBaseKey === 'function') {
-      const info = typeof signalRepository.getSessionInfo === 'function' ? await signalRepository.getSessionInfo(participant) : undefined
-      if (info) {
-        if (retryCount === 2) messageRetryManager.saveBaseKey(sessionId, ids[0], info.baseKey)
-        else if (retryCount > 2) {
-          if (messageRetryManager.hasSameBaseKey(sessionId, ids[0], info.baseKey)) { logger.warn({ participant, retryCount }, 'base key collision on retry, forcing fresh session'); await authState.keys.set({ session: { [sessionId]: null } }) }
-          messageRetryManager.deleteBaseKey(sessionId, ids[0])
-        }
-      }
-    }
-
-    let shouldRecreateSession = false, recreateReason = ''
-    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1 && !injectedFromBundle) {
-      try {
-        const hasSession = await signalRepository.validateSession(participant)
-        const result = messageRetryManager.shouldRecreateSession(participant, retryCount, hasSession.exists)
-        shouldRecreateSession = result.recreate; recreateReason = result.reason
-        if (shouldRecreateSession) { logger.debug({ participant, retryCount, reason: recreateReason }, 'recreating session for outgoing retry'); await authState.keys.set({ session: { [sessionId]: null } }) }
-      } catch (error) { logger.warn({ error, participant }, 'failed to check session recreation for outgoing retry') }
-    }
-
-    if (!injectedFromBundle) await assertSessions([participant], true)
-    if (isJidGroup(remoteJid)) await authState.keys.set({ 'sender-key-memory': { [remoteJid]: null } })
-    logger.debug({ participant, sendToAll, shouldRecreateSession, recreateReason, injectedFromBundle }, 'preparing retry recp')
-
-    for (const [i, msg] of msgs.entries()) {
-      if (!ids[i]) continue
-      if (msg && (await willSendMessageAgain(ids[i], participant))) {
-        await updateSendMessageAgainCount(ids[i], participant)
-        const msgRelayOpts = { messageId: ids[i] }
-        if (sendToAll) msgRelayOpts.useUserDevicesCache = false
-        else msgRelayOpts.participant = { jid: participant, count: +retryNode.attrs.count }
-        await relayMessage(key.remoteJid, msg, msgRelayOpts)
-      } else logger.debug({ jid: key.remoteJid, id: ids[i] }, 'recv retry request, but message not available')
-    }
-  }
-
-  // ── handleReceipt ─────────────────────────────────────────────────────────
-
-  const handleReceipt = async (node) => {
-    const { attrs, content } = node
-    const isLid = attrs.from.includes('lid')
-    const isNodeFromMe = areJidsSameUser(attrs.participant || attrs.from, isLid ? authState.creds.me?.lid : authState.creds.me?.id)
-    const remoteJid = !isNodeFromMe || isJidGroup(attrs.from) ? attrs.from : attrs.recipient
-    const fromMe = !attrs.recipient || ((attrs.type === 'retry' || attrs.type === 'sender') && isNodeFromMe)
-    const key = { remoteJid, id: '', fromMe, participant: attrs.participant }
-    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid }, 'ignoring receipt from jid'); await sendMessageAck(node); return }
-    const ids = [attrs.id]
-    if (Array.isArray(content)) ids.push(...getBinaryNodeChildren(content[0], 'item').map(i => i.attrs.id))
-    try {
-      await Promise.all([processingMutex.mutex(async () => {
-        const status = getStatusFromReceiptType(attrs.type)
-        if (typeof status !== 'undefined' && (status >= proto.WebMessageInfo.Status.SERVER_ACK || !isNodeFromMe)) {
-          if (isJidGroup(remoteJid) || isJidStatusBroadcast(remoteJid)) {
-            if (attrs.participant) {
-              const updateKey = status === proto.WebMessageInfo.Status.DELIVERY_ACK ? 'receiptTimestamp' : 'readTimestamp'
-              ev.emit('message-receipt.update', ids.map(id => ({ key: { ...key, id }, receipt: { userJid: jidNormalizedUser(attrs.participant), [updateKey]: +attrs.t } })))
-            }
-          } else ev.emit('messages.update', ids.map(id => ({ key: { ...key, id }, update: { status, messageTimestamp: toNumber(+(attrs.t ?? 0)) } })))
-        }
-        if (attrs.type === 'retry') {
-          key.participant = key.participant || attrs.from
-          const retryNode = getBinaryNodeChild(node, 'retry')
-          if (ids[0] && key.participant && (await willSendMessageAgain(ids[0], key.participant))) {
-            if (key.fromMe) {
-              try { await updateSendMessageAgainCount(ids[0], key.participant); logger.debug({ attrs, key }, 'recv retry request'); await sendMessagesAgain(key, ids, retryNode, node) }
-              catch (error) { logger.error({ key, ids, trace: error instanceof Error ? error.stack : 'Unknown error' }, 'error in sending message again') }
-            } else logger.info({ attrs, key }, 'recv retry for not fromMe message')
-          } else {
-            logger.info({ attrs, key, participant: key.participant }, 'retry limit exhausted - clearing broken session')
-            try {
-              await signalRepository.deleteSession([key.participant])
-              await msgRetryCache.del(`${ids[0]}:${key.participant}`)
-            } catch (err) { logger.error({ err, participant: key.participant }, 'failed to clear session/cache at retry exhaustion') }
-          }
-        }
-      })])
-    } finally { await sendMessageAck(node) }
-  }
-
-  // ── handleNotification ────────────────────────────────────────────────────
-
-  const handleNotification = async (node) => {
-    const remoteJid = node.attrs.from
-    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid, id: node.attrs.id }, 'ignored notification'); await sendMessageAck(node); return }
-    try {
-      await Promise.all([notificationMutex.mutex(async () => {
-        const msg = await processNotification(node)
-        if (msg) {
-          const fromMe = areJidsSameUser(node.attrs.participant || remoteJid, authState.creds.me.id)
-          const { senderAlt: participantAlt, addressingMode } = extractAddressingContext(node)
-          msg.key = { remoteJid, fromMe, participant: node.attrs.participant, participantAlt, addressingMode, id: node.attrs.id, ...(msg.key || {}) }
-          msg.participant ?? (msg.participant = node.attrs.participant)
-          msg.messageTimestamp = +node.attrs.t
-          await upsertMessage(proto.WebMessageInfo.fromObject(msg), 'append')
-        }
-      })])
-    } finally { await sendMessageAck(node) }
-  }
-
-  // ── handleMessage ─────────────────────────────────────────────────────────
-
-  const handleMessage = async (node) => {
-    if (shouldIgnoreJid(node.attrs.from) && node.attrs.from !== S_WHATSAPP_NET) { logger.debug({ key: node.attrs.key }, 'ignored message'); await sendMessageAck(node, NACK_REASONS.UnhandledError); return }
-
-    const encNode = getBinaryNodeChild(node, 'enc')
-    if (encNode && encNode.attrs.type === 'msmsg') {
-      const encIv = getBinaryNodeChildBuffer(encNode, 'enc_iv')
-      const encPayload = getBinaryNodeChildBuffer(encNode, 'enc_p') || encNode.content
-      if (!encIv || !encPayload) { logger.debug({ id: node.attrs.id, from: node.attrs.from, hasIv: !!encIv, hasPayload: !!encPayload }, 'msmsg missing enc_iv or enc_p, cannot decrypt'); await sendMessageAck(node); return }
-      try {
-        const messageSecret = authState.creds.myAppStateKeyId ? Buffer.from(authState.creds.myAppStateKeyId, 'base64') : undefined
-        if (!messageSecret) { logger.debug({ key: node.attrs.key }, 'no message secret for msmsg, skipping'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
-        const messageKey = { participant: node.attrs.participant || node.attrs.from, meId: authState.creds.me.id, meLid: authState.creds.me.lid, conversationJid: node.attrs.from, senderJid: node.attrs.participant, stanzaId: node.attrs.id, targetId: node.attrs.id }
-        const decrypted = await decryptMsmsgBotMessage(messageSecret, messageKey, { encPayload, encIv })
-        node.attrs._msmsgDecrypted = decodeDecryptedMsmsgMessage(decrypted)
-        logger.debug({ key: node.attrs.key }, 'decrypted msmsg bot message')
-      } catch (err) { logger.warn({ err, id: node.attrs.id }, 'failed to decrypt msmsg, falling back to nack'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
-    }
-
-    const { fullMessage: msg, category, author, decrypt } = decryptMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '', signalRepository, logger)
-    const alt = msg.key.participantAlt || msg.key.remoteJidAlt
-    if (!!alt) {
-      const altServer = jidDecode(alt)?.server
-      const primaryJid = msg.key.participant || msg.key.remoteJid
-      if (altServer === 'lid') { if (!(await signalRepository.lidMapping.getPNForLID(alt))) { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: alt, pn: primaryJid }]); await signalRepository.migrateSession(primaryJid, alt) } }
-      else { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: primaryJid, pn: alt }]); await signalRepository.migrateSession(alt, primaryJid) }
-    }
-
-    let acked = false
-    try {
-      await messageMutex.mutex(async () => {
-        await decrypt()
-        if (msg.key?.remoteJid && msg.key?.id && msg.message && messageRetryManager) messageRetryManager.addRecentMessage(msg.key.remoteJid, msg.key.id, msg.message)
-
-        if (msg.messageStubType === proto.WebMessageInfo.StubType.CIPHERTEXT && msg.category !== 'peer') {
-          if (msg?.messageStubParameters?.[0] === MISSING_KEYS_ERROR_TEXT) { acked = true; return sendMessageAck(node, NACK_REASONS.ParsingError) }
-          if (msg.messageStubParameters?.[0] === NO_MESSAGE_FOUND_ERROR_TEXT) {
-            const unavailableNode = getBinaryNodeChild(node, 'unavailable')
-            const unavailableType = unavailableNode?.attrs?.type
-            if (['bot_unavailable_fanout', 'hosted_unavailable_fanout', 'view_once_unavailable_fanout'].includes(unavailableType)) { logger.debug({ msgId: msg.key.id, unavailableType }, 'skipping placeholder resend for excluded unavailable type'); acked = true; return sendMessageAck(node) }
-            const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
-            if (messageAge > PLACEHOLDER_MAX_AGE_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge }, 'skipping placeholder resend for old message'); acked = true; return sendMessageAck(node) }
-            const cleanKey = { remoteJid: msg.key.remoteJid, fromMe: msg.key.fromMe, id: msg.key.id, participant: msg.key.participant }
-            const msgData = { key: msg.key, messageTimestamp: msg.messageTimestamp, pushName: msg.pushName, participant: msg.participant, verifiedBizName: msg.verifiedBizName }
-            requestPlaceholderResend(cleanKey, msgData).then(requestId => { if (requestId && requestId !== 'RESOLVED') { logger.debug({ msgId: msg.key.id, requestId }, 'requested placeholder resend for unavailable message'); ev.emit('messages.update', [{ key: msg.key, update: { messageStubParameters: [NO_MESSAGE_FOUND_ERROR_TEXT, requestId] } }]) } }).catch(err => logger.warn({ err, msgId: msg.key.id }, 'failed to request placeholder resend for unavailable message'))
-            acked = true; await sendMessageAck(node)
-          } else {
-            if ((msg.messageStubParameters?.[0] || '').includes('InvalidPreKeyId')) { logger.debug({ msgId: msg.key.id, remoteJid: msg.key.remoteJid }, 'skipping retry for InvalidPreKeyId, sender must re-establish session'); acked = true; return sendMessageAck(node, NACK_REASONS.UnhandledError) }
-            if (isJidStatusBroadcast(msg.key.remoteJid)) {
-              const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
-              if (messageAge > STATUS_EXPIRY_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge, remoteJid: msg.key.remoteJid }, 'skipping retry for expired status message'); acked = true; return sendMessageAck(node) }
-            }
-            retryMutex.mutex(async () => {
-              try { if (!ws.isOpen) { logger.debug({ node }, 'Connection closed, skipping retry'); return }; await sendRetryRequest(node, true); if (retryRequestDelayMs) await delay(retryRequestDelayMs) }
-              catch (err) { logger.error({ err }, 'Retry mechanism failed'); try { await sendRetryRequest(node, !getBinaryNodeChild(node, 'enc')) } catch (retryErr) { logger.error({ retryErr }, 'Final retry attempt failed') } }
-              acked = true; await sendMessageAck(node, NACK_REASONS.UnhandledError)
-            })
-          }
-        } else {
-          if (messageRetryManager && msg.key.id) messageRetryManager.cancelPendingPhoneRequest(msg.key.id)
-          const isNewsletter = isJidNewsletter(msg.key.remoteJid)
-          if (!isNewsletter) {
-            let type = undefined, participant = msg.key.participant
-            if (category === 'peer') type = 'peer_msg'
-            else if (msg.key.fromMe) { type = 'sender'; if (isLidUser(msg.key.remoteJid) || isLidUser(msg.key.remoteJidAlt)) participant = author }
-            else if (!sendActiveReceipts) type = 'inactive'
-            acked = true; await sendReceipt(msg.key.remoteJid, participant, [msg.key.id], type)
-            if (getHistoryMsg(msg.message)) await sendReceipt(jidNormalizedUser(msg.key.remoteJid), undefined, [msg.key.id], 'hist_sync')
-          } else { acked = true; await sendMessageAck(node); logger.debug({ key: msg.key }, 'processed newsletter message without receipts') }
-        }
-
-        cleanMessage(msg, authState.creds.me.id, authState.creds.me.lid)
-
-        if (!msg.key.fromMe) {
-          try {
-            const info = extractReportingInfoFromStanza(node)
-            if (info) {
-              const senderJid = msg.key.participant || author || msg.key.remoteJid
-              const contentType = msg.message ? getContentType(msg.message) : undefined
-              config.reportingInfoStore.add(senderJid, { stanzaId: info.stanzaId, timestamp: info.timestamp || Number(msg.messageTimestamp) || 0, reportingTag: info.reportingTag, text: extractMessageText(msg), pushName: msg.pushName || node.attrs?.notify || '', messageType: contentType === 'conversation' || contentType === 'extendedTextMessage' ? 'text' : contentType || 'text', fromJid: senderJid })
-            }
-          } catch (storeErr) { logger.warn({ err: storeErr, key: msg.key }, 'failed to store reporting_tag') }
-        }
-
-        await upsertMessage(msg, node.attrs.offline ? 'append' : 'notify')
-      })
-    } catch (error) {
-      const isClosed = error?.message?.includes('Connection Closed') || error?.output?.statusCode === 428
-      if (isClosed) logger.debug({ msg: error?.message }, 'Connection closed while handling message')
-      else logger.error({ error, stack: error?.stack, msg: error?.message || String(error), node: binaryNodeToString(node) }, 'error in handling message')
-      if (!acked) await sendMessageAck(node, NACK_REASONS.UnhandledError).catch(ackErr => logger.error({ ackErr }, 'failed to ack message after error'))
-    }
-  }
-
-  // ── handleCall ────────────────────────────────────────────────────────────
-
-  const handleCall = async (node) => {
-    const { attrs } = node
-    const [infoChild] = getAllBinaryNodeChildren(node)
-    if (!infoChild) throw new Boom('Missing call info in call node')
-    const status = getCallStatusFromNode(infoChild)
-    const callId = infoChild.attrs['call-id']
-    const from = infoChild.attrs.from || infoChild.attrs['call-creator']
-    const call = { chatId: attrs.from, from, callerPn: infoChild.attrs['caller_pn'], id: callId, date: new Date(+attrs.t * 1000), offline: !!attrs.offline, status }
-    if (status === 'offer') { call.isVideo = !!getBinaryNodeChild(infoChild, 'video'); call.isGroup = infoChild.attrs.type === 'group' || !!infoChild.attrs['group-jid']; call.groupJid = infoChild.attrs['group-jid']; await callOfferCache.set(call.id, call) }
-    const existingCall = await callOfferCache.get(call.id)
-    if (existingCall) { call.isVideo = existingCall.isVideo; call.isGroup = existingCall.isGroup; call.callerPn = call.callerPn || existingCall.callerPn }
-    if (['reject', 'accept', 'timeout', 'terminate'].includes(status)) await callOfferCache.del(call.id)
-    ev.emit('call', [call])
-    await sendMessageAck(node)
-  }
-
-  // ── handleBadAck ──────────────────────────────────────────────────────────
-
-  const handleBadAck = async ({ attrs }) => {
-    const key = { remoteJid: attrs.from, fromMe: true, id: attrs.id }
-    if (!attrs.error) return
-    const isReachoutTimelocked = attrs.error === String(NACK_REASONS.SenderReachoutTimelocked)
-    if (attrs.error === SERVER_ERROR_CODES.MessageAccountRestriction) {
-      logger.warn({ msgId: attrs.id, from: attrs.from }, 'error 463: account restricted or missing tctoken for contact')
-      const ackFrom = attrs.from
-      if (ackFrom && !inFlight463Recoveries.has(ackFrom)) {
-        inFlight463Recoveries.add(ackFrom)
-        void (async () => {
-          try {
-            const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
-            const tcStorageJid = await resolveTcTokenJid(ackFrom, getLIDForPN)
-            const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
-            const issueJid = await resolveIssuanceJid(ackFrom, issueToLid, getLIDForPN, getPNForLID)
-            const result = await issuePrivacyTokens([issueJid], unixTimestampSeconds())
-            await storeTcTokensFromIqResult({ result, fallbackJid: tcStorageJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
-            logger.debug({ from: ackFrom }, 'completed 463 token recovery issuance')
-          } catch (err) { logger.debug({ from: ackFrom, err: err?.message }, 'failed 463 token recovery issuance') }
-          finally { inFlight463Recoveries.delete(ackFrom) }
-        })()
-      }
-    } else if (attrs.error === SERVER_ERROR_CODES.SmaxInvalid) {
-      logger.warn({ msgId: attrs.id, from: attrs.from }, 'smax-invalid (479): stale device session or malformed addressing')
-    } else if (isReachoutTimelocked) {
-      await fetchAccountReachoutTimelock().catch(err => logger.warn({ err }, 'failed to fetch reachout timelock'))
-      logger.warn({ attrs }, 'received error in ack')
-    } else {
-      logger.warn({ attrs }, 'received error in ack')
-    }
-    ev.emit('messages.update', [{ key, update: { status: WAMessageStatus.ERROR, messageStubParameters: isReachoutTimelocked ? [attrs.error, ACCOUNT_RESTRICTED_TEXT] : [attrs.error] } }])
-  }
-
-  // ── Offline node processor ────────────────────────────────────────────────
-
-  const processNodeWithBuffer = async (node, identifier, exec) => { ev.buffer(); await exec(node, false).catch(err => onUnexpectedError(err, identifier)); ev.flush() }
-  const yieldToEventLoop = () => new Promise(resolve => setImmediate(resolve))
-
-  const makeOfflineNodeProcessor = () => {
-    const nodeProcessorMap = new Map([['message', handleMessage], ['call', handleCall], ['receipt', handleReceipt], ['notification', handleNotification]])
-    const nodes = []
-    let isProcessing = false
-    const enqueue = (type, node) => {
-      nodes.push({ type, node })
-      if (isProcessing) return
-      isProcessing = true;
-      (async () => {
-        let processedInBatch = 0
-        while (nodes.length && ws.isOpen) {
-          const { type, node } = nodes.shift()
-          const processor = nodeProcessorMap.get(type)
-          if (!processor) { onUnexpectedError(new Error(`unknown offline node type: ${type}`), 'processing offline node'); continue }
-          await processor(node).catch(err => onUnexpectedError(err, `processing offline ${type}`))
-          if (++processedInBatch >= 10) { processedInBatch = 0; await yieldToEventLoop() }
-        }
-        isProcessing = false
-      })().catch(error => onUnexpectedError(error, 'processing offline nodes'))
-    }
-    return { enqueue }
-  }
-
-  const offlineNodeProcessor = makeOfflineNodeProcessor()
-
-  const processNode = async (type, node, identifier, exec) => {
-    const from = node.attrs.from
-    if (from && from !== S_WHATSAPP_NET && shouldIgnoreJid(from)) { await sendMessageAck(node, type === 'message' ? NACK_REASONS.UnhandledError : undefined); return }
-    if (node.attrs.offline) offlineNodeProcessor.enqueue(type, node)
-    else await processNodeWithBuffer(node, identifier, exec)
-  }
-
-  // ── WS event bindings ─────────────────────────────────────────────────────
-
-  ws.on('CB:message', async (node) => { await processNode('message', node, 'processing message', handleMessage) })
-  ws.on('CB:call', async (node) => { await processNode('call', node, 'handling call', handleCall) })
-  ws.on('CB:receipt', async (node) => { await processNode('receipt', node, 'handling receipt', handleReceipt) })
-  ws.on('CB:notification', async (node) => { await processNode('notification', node, 'handling notification', handleNotification) })
-  ws.on('CB:ack,class:message', (node) => { handleBadAck(node).catch(error => onUnexpectedError(error, 'handling bad ack')) })
-
-  ev.on('call', async ([call]) => {
-    if (!call) return
-    if (call.status === 'timeout' || (call.status === 'offer' && call.isGroup)) {
-      const msg = { key: { remoteJid: call.chatId, id: call.id, fromMe: false }, messageTimestamp: unixTimestampSeconds(call.date) }
-      if (call.status === 'timeout') msg.messageStubType = call.isGroup ? (call.isVideo ? WAMessageStubType.CALL_MISSED_GROUP_VIDEO : WAMessageStubType.CALL_MISSED_GROUP_VOICE) : (call.isVideo ? WAMessageStubType.CALL_MISSED_VIDEO : WAMessageStubType.CALL_MISSED_VOICE)
-      else msg.message = { call: { callKey: Buffer.from(call.id) } }
-      await upsertMessage(proto.WebMessageInfo.fromObject(msg), call.offline ? 'append' : 'notify')
-    }
-  })
-
-  // ── TC token pruning ──────────────────────────────────────────────────────
-
-  let lastTcTokenPruneTs = 0
-  const pruneExpiredTcTokens = async () => {
-    try {
-      await tcTokenIndexLoaded
-      const persisted = await readTcTokenIndex(authState.keys)
-      const allJids = new Set([...tcTokenKnownJids, ...persisted])
-      if (!allJids.size) return
-      const jids = [...allJids]
-      const allTokens = await authState.keys.get('tctoken', jids)
-      const writes = {}, survivors = new Set()
-      let mutated = 0
-      for (const jid of jids) {
-        const entry = allTokens[jid]
-        if (!entry) { mutated++; continue }
-        const hasPeerToken = !!entry.token?.length
-        const peerTokenExpired = hasPeerToken && isTcTokenExpired(entry.timestamp)
-        const hasSenderTs = entry.senderTimestamp !== undefined
-        const senderTsExpired = hasSenderTs && isTcTokenExpired(entry.senderTimestamp)
-        const keepPeer = hasPeerToken && !peerTokenExpired
-        const keepSender = hasSenderTs && !senderTsExpired
-        if (!keepPeer && !keepSender) { writes[jid] = null; mutated++ }
-        else if (peerTokenExpired && keepSender) { writes[jid] = { token: Buffer.alloc(0), senderTimestamp: entry.senderTimestamp }; survivors.add(jid); mutated++ }
-        else survivors.add(jid)
-      }
-      if (mutated === 0) return
-      await authState.keys.set({ tctoken: { ...writes, [TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify([...survivors])) } } })
-      tcTokenKnownJids.clear(); for (const jid of survivors) tcTokenKnownJids.add(jid)
-      logger.debug({ mutated, remaining: survivors.size }, 'pruned expired tctokens')
-    } catch (err) { logger.warn({ err: err?.message }, 'failed to prune expired tctokens') }
-  }
-
-  ev.on('connection.update', ({ isOnline, connection }) => {
-    if (typeof isOnline !== 'undefined') { sendActiveReceipts = isOnline; logger.trace(`sendActiveReceipts set to "${sendActiveReceipts}"`) }
-    if (connection === 'close' && tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined; try { void Promise.resolve(flushTcTokenIndex()).catch(() => { }) } catch { } }
-    if (isOnline) { const now = Date.now(); if (now - lastTcTokenPruneTs >= 86_400_000) { lastTcTokenPruneTs = now; void pruneExpiredTcTokens() } }
-  })
-
-  registerSocketEndHandler(() => {
-    if (!config.msgRetryCounterCache && msgRetryCache.close) msgRetryCache.close()
-    if (!config.callOfferCache && callOfferCache.close) callOfferCache.close()
-    identityAssertDebounce.close()
-    sendActiveReceipts = false
-  })
-
-  return { ...sock, sendMessageAck, sendRetryRequest, rejectCall, offerCall, fetchMessageHistory, requestPlaceholderResend, requestContactRefresh, messageRetryManager, tcTokenIndexLoaded }
+import NodeCache from '@cacheable/node-cache'
+import { Boom } from '@hapi/boom'
+import { randomBytes } from 'crypto'
+import { proto } from '../../WAProto/index.js'
+import { DEFAULT_CACHE_TTLS, KEY_BUNDLE_TYPE, MIN_PREKEY_COUNT, PLACEHOLDER_MAX_AGE_SECONDS, STATUS_EXPIRY_SECONDS } from '../Defaults/index.js'
+import { ReachoutTimelockEnforcementType, WAMessageStatus, WAMessageStubType } from '../Types/index.js'
+import {
+  aesDecryptCTR, aesEncryptGCM, cleanMessage, Curve, decodeMediaRetryNode,
+  decodeMessageNode, makeMutex, decryptMessageNode, delay, derivePairingCodeKey,
+  encodeBigEndian, encodeSignedDeviceIdentity, extractAddressingContext,
+  extractE2ESessionFromRetryReceipt, getCallStatusFromNode, getHistoryMsg,
+  getNextPreKeys, getStatusFromReceiptType, extractMessageText,
+  handleIdentityChange, hkdf, MISSING_KEYS_ERROR_TEXT, NACK_REASONS,
+  NO_MESSAGE_FOUND_ERROR_TEXT, SERVER_ERROR_CODES, toNumber, unixTimestampSeconds,
+  xmppPreKey, xmppSignedPreKey, ACCOUNT_RESTRICTED_TEXT, buildMergedTcTokenIndexWrite,
+  isTcTokenExpired, readTcTokenIndex, resolveTcTokenJid, resolveIssuanceJid,
+  storeTcTokensFromIqResult, TC_TOKEN_INDEX_KEY, decryptMsmsgBotMessage,
+  decodeDecryptedMsmsgMessage, extractReportingInfoFromStanza, getContentType,
+} from '../Utils/index.js'
+import {
+  areJidsSameUser, binaryNodeToString, getAllBinaryNodeChildren, getBinaryNodeChild,
+  getBinaryNodeChildBuffer, getBinaryNodeChildren, getBinaryNodeChildString,
+  getBinaryNodeChildUInt, isJidGroup, isJidNewsletter, isJidStatusBroadcast,
+  isLidUser, isPnUser, jidDecode, jidNormalizedUser, S_WHATSAPP_NET, jidEncode,
+} from '../WABinary/index.js'
+import { extractGroupMetadata } from './groups.js'
+import { makeMessagesSocket } from './messages-send.js'
+
+// ─── Pure stanza builders ─────────────────────────────────────────────────────
+
+export const buildGroupCallStanza = ({ id, to, callId, callCreator, offerContent }) => ({
+  tag: 'call',
+  attrs: { id, to },
+  content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': callCreator, type: 'group', 'group-jid': to }, content: offerContent }]
+})
+
+export const buildGroupCallCancelStanza = ({ to, callId, callCreator }) => ({
+  tag: 'call',
+  attrs: { from: callCreator, to },
+  content: [{ tag: 'terminate', attrs: { 'call-id': callId, 'call-creator': callCreator, reason: 'user-terminated', count: '0' }, content: undefined }]
+})
+
+const ENFORCEMENT_TYPE_VALUES = new Set(Object.values(ReachoutTimelockEnforcementType))
+const isValidEnforcementType = (value) => typeof value === 'string' && ENFORCEMENT_TYPE_VALUES.has(value)
+
+// ─── Socket ───────────────────────────────────────────────────────────────────
+
+export const makeMessagesRecvSocket = (config) => {
+  const { logger, retryRequestDelayMs, maxMsgRetryCount, getMessage, shouldIgnoreJid, enableAutoSessionRecreation } = config
+  const sock = makeMessagesSocket(config)
+  const { ev, authState, ws, processingMutex, signalRepository, query, upsertMessage, resyncAppState, onUnexpectedError, assertSessions, sendNode, relayMessage, sendReceipt, uploadPreKeys, sendPeerDataOperationMessage, messageRetryManager, registerSocketEndHandler, issuePrivacyTokens, fetchAccountReachoutTimelock, placeholderResendCache: sockPlaceholderResendCache } = sock
+
+  const getLIDForPN = signalRepository.lidMapping.getLIDForPN.bind(signalRepository.lidMapping)
+  const { messageMutex, notificationMutex, receiptMutex: _receiptMutex, placeholderResendCache } = sock
+  const retryMutex = makeMutex()
+  const msgRetryCache = config.msgRetryCounterCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.MSG_RETRY, useClones: false })
+  const callOfferCache = config.callOfferCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.CALL_OFFER, useClones: false })
+  const identityAssertDebounce = new NodeCache({ stdTTL: 5, useClones: false })
+  const inFlightPreKeyLow = new Set()
+  const inFlight463Recoveries = new Set()
+
+  let sendActiveReceipts = false
+
+  // ── PDO helpers ───────────────────────────────────────────────────────────
+
+  const fetchMessageHistory = async (count, oldestMsgKey, oldestMsgTimestamp) => {
+    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
+    return sendPeerDataOperationMessage({ historySyncOnDemandRequest: { chatJid: oldestMsgKey.remoteJid, oldestMsgFromMe: oldestMsgKey.fromMe, oldestMsgId: oldestMsgKey.id, oldestMsgTimestampMs: oldestMsgTimestamp, onDemandMsgCount: count }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.HISTORY_SYNC_ON_DEMAND })
+  }
+
+  const requestPlaceholderResend = async (messageKey, msgData) => {
+    if (!authState.creds.me?.id) throw new Boom('Not authenticated')
+    if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'already requested resend'); return }
+    await placeholderResendCache.set(messageKey?.id, msgData || true)
+    await delay(2000)
+    if (!(await placeholderResendCache.get(messageKey?.id))) { logger.debug({ messageKey }, 'message received while resend requested'); return 'RESOLVED' }
+    setTimeout(async () => { if (await placeholderResendCache.get(messageKey?.id)) { logger.debug({ messageKey }, 'PDO message without response after 8 seconds. Phone possibly offline'); await placeholderResendCache.del(messageKey?.id) } }, 8000)
+    return sendPeerDataOperationMessage({ placeholderMessageResendRequest: [{ messageKey }], peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.PLACEHOLDER_MESSAGE_RESEND })
+  }
+
+  const requestContactRefresh = async (jids) => {
+    if (!jids?.length) return
+    return sendPeerDataOperationMessage({ contactRefreshRequest: { jids: Array.isArray(jids) ? jids : [jids] }, peerDataOperationRequestType: proto.Message.PeerDataOperationRequestType.CONTACT_REFRESH_REQUEST })
+  }
+
+  // ── Newsletter notifications ──────────────────────────────────────────────
+
+  const handleReachoutTimelockNotification = (data) => {
+    const payload = data.xwa2_notify_account_reachout_timelock
+    if (!payload) { logger.warn('reachout timelock notification missing payload'); return }
+    if (!payload.is_active) { ev.emit('connection.update', { reachoutTimeLock: { isActive: false, enforcementType: ReachoutTimelockEnforcementType.DEFAULT } }); return }
+    const timeEnforcementEnds = payload.time_enforcement_ends ? new Date(parseInt(payload.time_enforcement_ends, 10) * 1000) : new Date(Date.now() + 60000)
+    const enforcementType = isValidEnforcementType(payload.enforcement_type) ? payload.enforcement_type : ReachoutTimelockEnforcementType.DEFAULT
+    logger.info({ enforcementType, timeEnforcementEnds }, 'reachout timelock restriction set')
+    ev.emit('connection.update', { reachoutTimeLock: { isActive: true, timeEnforcementEnds, enforcementType } })
+  }
+
+  const handleMessageCappingNotification = (data) => {
+    const payload = data.xwa2_notify_new_chat_messages_capping_info_update
+    if (!payload) { logger.warn('message capping notification missing payload'); return }
+    logger.info({ payload }, 'received message capping update')
+    ev.emit('message-capping.update', payload)
+  }
+
+  const handleLegacyMexNewsletterNotification = async (node) => {
+    const mexNode = getBinaryNodeChild(node, 'mex')
+    const updateNode = mexNode?.content ? null : getBinaryNodeChild(node, 'update') || getAllBinaryNodeChildren(node)[0]
+    const payloadNode = mexNode?.content ? mexNode : updateNode
+    if (!payloadNode?.content) { logger.warn({ node: binaryNodeToString(node) }, 'invalid mex newsletter notification'); return }
+    let data
+    try {
+      const payloadContent = payloadNode.content
+      if (Array.isArray(payloadContent)) { logger.warn({ payloadNode }, 'invalid mex newsletter notification payload format'); return }
+      const contentBuf = typeof payloadContent === 'string' ? Buffer.from(payloadContent, 'binary') : Buffer.from(payloadContent)
+      data = JSON.parse(contentBuf.toString())
+    } catch (error) { logger.error({ err: error, node: binaryNodeToString(node) }, 'failed to parse mex newsletter notification'); return }
+    const operation = data?.operation ?? payloadNode?.attrs?.op_name
+    let updates = data?.updates
+    if (!updates) { const linkedProfiles = data?.data?.xwa2_notify_linked_profiles; if (linkedProfiles) updates = [linkedProfiles] }
+    if (!updates || !operation) { logger.warn({ data }, 'invalid mex newsletter notification content'); return }
+    logger.info({ operation, updates }, 'got mex newsletter notification')
+    switch (operation) {
+      case 'NotificationNewsletterUpdate':
+        for (const update of updates) if (update.jid && update.settings && Object.keys(update.settings).length > 0) ev.emit('newsletter-settings.update', { id: update.jid, update: update.settings })
+        break
+      case 'NotificationNewsletterAdminPromote':
+        for (const update of updates) if (update.jid && update.user) ev.emit('newsletter-participants.update', { id: update.jid, author: node.attrs.from, user: update.user, new_role: 'ADMIN', action: 'promote' })
+        break
+      case 'NotificationLinkedProfilesUpdates':
+        for (const update of updates) {
+          const lid = update?.jid
+          const addedProfiles = Array.isArray(update?.added_profiles) ? update.added_profiles : []
+          const mappings = []
+          for (const profile of addedProfiles) {
+            const pn = typeof profile === 'string' ? profile : (profile?.pn ?? profile?.jid ?? null)
+            if (lid && pn) { const mapping = { lid, pn }; ev.emit('lid-mapping.update', mapping); mappings.push(mapping) }
+          }
+          await signalRepository.lidMapping.storeLIDPNMappings(mappings)
+        }
+        break
+      default:
+        logger.info({ operation, data }, 'unhandled mex newsletter notification')
+    }
+  }
+
+  const handleMexNotification = async (node) => {
+    const updateNode = getBinaryNodeChild(node, 'update')
+    if (!updateNode) { await handleLegacyMexNewsletterNotification(node); return }
+    const opName = updateNode.attrs?.op_name
+    if (!opName) { logger.warn({ node: binaryNodeToString(node) }, 'mex notification missing op_name, fallback to legacy'); await handleLegacyMexNewsletterNotification(node); return }
+    let mexResponse
+    try { mexResponse = JSON.parse(updateNode.content.toString()) } catch (error) { logger.error({ err: error, opName }, 'failed to parse mex notification JSON'); return }
+    if (mexResponse.errors?.length) { logger.warn({ errors: mexResponse.errors, opName }, 'mex notification has GQL errors'); return }
+    const data = mexResponse.data
+    if (!data) { logger.warn({ opName }, 'mex notification has null data'); return }
+    logger.debug({ opName }, 'processing mex notification')
+    switch (opName) {
+      case 'NotificationUserReachoutTimelockUpdate': handleReachoutTimelockNotification(data); break
+      case 'MessageCappingInfoNotification': handleMessageCappingNotification(data); break
+      case 'NotificationNewsletterJoin':
+        ev.emit('newsletter.join', data?.xwa2_notify_newsletter_on_join); break
+      case 'NotificationNewsletterUserSettingChange':
+        ev.emit('newsletter.viewer-settings.update', data?.xwa2_notify_newsletter_on_user_setting_change); break
+      default: {
+        const xwa2Key = Object.keys(data).find(k => k.startsWith('xwa2_notify_'))
+        if (xwa2Key) {
+          ev.emit('newsletter.update', { type: opName, data: data[xwa2Key] })
+          logger.debug({ opName, xwa2Key }, 'emitted newsletter update from xwa2 key')
+        } else {
+          await handleLegacyMexNewsletterNotification(node)
+        }
+        break
+      }
+    }
+  }
+
+  const handleNewsletterNotification = async (node) => {
+    const from = node.attrs.from
+    const children = getAllBinaryNodeChildren(node)
+    const author = node.attrs.participant
+    for (const child of children) {
+      logger.debug({ from, child }, 'got newsletter notification')
+      switch (child.tag) {
+        case 'reaction':
+          ev.emit('newsletter.reaction', { id: from, server_id: child.attrs.message_id, reaction: { code: getBinaryNodeChildString(child, 'reaction'), count: 1 } })
+          break
+        case 'view':
+          ev.emit('newsletter.view', { id: from, server_id: child.attrs.message_id, count: parseInt(child.content?.toString() || '0', 10) })
+          break
+        case 'participant':
+          ev.emit('newsletter-participants.update', { id: from, author, user: child.attrs.jid, action: child.attrs.action, new_role: child.attrs.role })
+          break
+        case 'update':
+          const settingsNode = getBinaryNodeChild(child, 'settings')
+          if (settingsNode) {
+            const update = {}
+            const nameNode = getBinaryNodeChild(settingsNode, 'name')
+            if (nameNode?.content) update.name = nameNode.content.toString()
+            const descNode = getBinaryNodeChild(settingsNode, 'description')
+            if (descNode?.content) update.description = descNode.content.toString()
+            ev.emit('newsletter-settings.update', { id: from, update })
+          }
+          break
+        case 'message':
+          const plaintextNode = getBinaryNodeChild(child, 'plaintext')
+          if (plaintextNode?.content) {
+            try {
+              const buf = typeof plaintextNode.content === 'string' ? Buffer.from(plaintextNode.content, 'binary') : Buffer.from(plaintextNode.content)
+              const messageProto = proto.Message.decode(buf).toJSON()
+              const fullMessage = proto.WebMessageInfo.fromObject({ key: { remoteJid: from, id: child.attrs.message_id || child.attrs.server_id, fromMe: false }, message: messageProto, messageTimestamp: +child.attrs.t }).toJSON()
+              await upsertMessage(fullMessage, 'append')
+            } catch (error) { logger.error({ error }, 'Failed to decode plaintext newsletter message') }
+          }
+          break
+        default:
+          logger.warn({ node }, 'Unknown newsletter notification')
+      }
+    }
+  }
+
+  // ── ACK / call helpers ────────────────────────────────────────────────────
+
+  const sendMessageAck = async (node, errorCode) => {
+    const { tag, attrs, content } = node
+    const hasUnavailable = !!getBinaryNodeChild({ tag, attrs, content }, 'unavailable')
+    const stanza = { tag: 'ack', attrs: { id: attrs.id, to: attrs.from, class: tag } }
+    if (errorCode) stanza.attrs.error = errorCode.toString()
+    if (attrs.participant) stanza.attrs.participant = attrs.participant
+    if (attrs.recipient) stanza.attrs.recipient = attrs.recipient
+    if (attrs.type || hasUnavailable || errorCode) stanza.attrs.type = attrs.type
+    if (tag === 'message' && authState.creds.me?.id) stanza.attrs.from = authState.creds.me.id
+    logger.debug({ recv: { tag, attrs }, sent: stanza.attrs }, 'sent ack')
+    try { await sendNode(stanza) } catch (error) {
+      if (error?.output?.statusCode === 428 || error?.message?.includes('Connection')) logger.warn({ id: attrs.id, error: error?.message }, 'Failed to send ACK (connection closed) - message already received')
+      else throw error
+    }
+  }
+
+  const rejectCall = async (callId, callFrom) => {
+    await query({ tag: 'call', attrs: { from: authState.creds.me.id, to: callFrom }, content: [{ tag: 'reject', attrs: { 'call-id': callId, 'call-creator': callFrom, count: '0' }, content: undefined }] })
+  }
+
+  const offerCall = async (toJid, isVideo = false) => {
+    const callId = randomBytes(16).toString('hex').toUpperCase().substring(0, 64)
+    const offerContent = []
+    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '16000' }, content: undefined })
+    offerContent.push({ tag: 'audio', attrs: { enc: 'opus', rate: '8000' }, content: undefined })
+    if (isVideo) offerContent.push({ tag: 'video', attrs: { orientation: '0', screen_width: '1920', screen_height: '1080', device_orientation: '0', enc: 'vp8', dec: 'vp8' } })
+    offerContent.push({ tag: 'net', attrs: { medium: '3' }, content: undefined })
+    offerContent.push({ tag: 'capability', attrs: { ver: '1' }, content: new Uint8Array([1, 4, 255, 131, 207, 4]) })
+    offerContent.push({ tag: 'encopt', attrs: { keygen: '2' }, content: undefined })
+    const encKey = randomBytes(32)
+    const devices = (await getUSyncDevices([toJid], true, false)).map(({ user, device }) => jidEncode(user, 's.whatsapp.net', device))
+    await assertSessions(devices, true)
+    const { nodes: destinations, shouldIncludeDeviceIdentity } = await createParticipantNodes(devices, { call: { callKey: encKey } }, {})
+    offerContent.push({ tag: 'destination', attrs: {}, content: destinations })
+    if (shouldIncludeDeviceIdentity) offerContent.push({ tag: 'device-identity', attrs: {}, content: encodeSignedDeviceIdentity(authState.creds.account, true) })
+    await query({ tag: 'call', attrs: { to: toJid }, content: [{ tag: 'offer', attrs: { 'call-id': callId, 'call-creator': authState.creds.me.id }, content: offerContent }] })
+    return { callId, toJid, isVideo }
+  }
+
+  // ── Retry logic ───────────────────────────────────────────────────────────
+
+  const sendRetryRequest = async (node, forceIncludeKeys = false) => {
+    const { fullMessage } = decodeMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '')
+    const { key: msgKey } = fullMessage
+    const msgId = msgKey.id
+
+    if (messageRetryManager) {
+      if (messageRetryManager.hasExceededMaxRetries(msgId)) { logger.debug({ msgId }, 'reached retry limit with new retry manager, clearing'); messageRetryManager.markRetryFailed(msgId); return }
+      const retryCount = messageRetryManager.incrementRetryCount(msgId)
+      await msgRetryCache.set(`${msgId}:${msgKey?.participant}`, retryCount)
+    } else {
+      const key = `${msgId}:${msgKey?.participant}`
+      let retryCount = (await msgRetryCache.get(key)) || 0
+      if (retryCount >= maxMsgRetryCount) { logger.debug({ retryCount, msgId }, 'reached retry limit, clearing'); await msgRetryCache.del(key); return }
+      await msgRetryCache.set(key, retryCount + 1)
+    }
+
+    const retryCount = (await msgRetryCache.get(`${msgId}:${msgKey?.participant}`)) || 1
+    const { account, signedPreKey, signedIdentityKey: identityKey } = authState.creds
+    const fromJid = node.attrs.from
+    let shouldRecreateSession = false, recreateReason = ''
+
+    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1) {
+      try {
+        const sessionId = signalRepository.jidToSignalProtocolAddress(fromJid)
+        const hasSession = await signalRepository.validateSession(fromJid)
+        let lidJid = null
+        if (isPnUser(fromJid)) lidJid = await signalRepository.lidMapping.getLIDForPN(fromJid)
+        const result = messageRetryManager.shouldRecreateSession(fromJid, retryCount, hasSession.exists)
+        shouldRecreateSession = result.recreate; recreateReason = result.reason
+        if (shouldRecreateSession) {
+          logger.debug({ fromJid, lidJid, retryCount, reason: recreateReason }, 'recreating session for retry')
+          await authState.keys.set({ session: { [sessionId]: null } })
+          if (lidJid) await authState.keys.set({ session: { [signalRepository.jidToSignalProtocolAddress(lidJid)]: null } })
+          forceIncludeKeys = true
+        }
+      } catch (error) { logger.warn({ error, fromJid }, 'failed to check session recreation') }
+    }
+
+    if (retryCount <= 2) {
+      if (messageRetryManager) {
+        messageRetryManager.schedulePhoneRequest(msgId, async () => {
+          try { const requestId = await requestPlaceholderResend(msgKey); logger.debug(`sendRetryRequest: requested placeholder resend (${requestId}) for message ${msgId} (scheduled)`) }
+          catch (error) { logger.warn({ error, msgId }, 'failed to send scheduled phone request') }
+        })
+      } else {
+        const id = await requestPlaceholderResend(msgKey)
+        logger.debug(`sendRetryRequest: requested placeholder resend for message ${id}`)
+      }
+    }
+
+    const deviceIdentity = encodeSignedDeviceIdentity(account, true)
+    await authState.keys.transaction(async () => {
+      const receipt = { tag: 'receipt', attrs: { id: msgId, type: 'retry', to: node.attrs.from }, content: [{ tag: 'retry', attrs: { count: retryCount.toString(), id: node.attrs.id, t: node.attrs.t, v: '1', error: '0' } }, { tag: 'registration', attrs: {}, content: encodeBigEndian(authState.creds.registrationId) }] }
+      if (node.attrs.recipient) receipt.attrs.recipient = node.attrs.recipient
+      if (node.attrs.participant) receipt.attrs.participant = node.attrs.participant
+      if (retryCount > 1 || forceIncludeKeys || shouldRecreateSession) {
+        const { update, preKeys } = await getNextPreKeys(authState, 1)
+        const [keyId] = Object.keys(preKeys)
+        const key = preKeys[+keyId]
+        receipt.content.push({ tag: 'keys', attrs: {}, content: [{ tag: 'type', attrs: {}, content: Buffer.from(KEY_BUNDLE_TYPE) }, { tag: 'identity', attrs: {}, content: identityKey.public }, xmppPreKey(key, +keyId), xmppSignedPreKey(signedPreKey), { tag: 'device-identity', attrs: {}, content: deviceIdentity }] })
+        ev.emit('creds.update', update)
+      }
+      await sendNode(receipt)
+      logger.info({ msgAttrs: node.attrs, retryCount }, 'sent retry receipt')
+    }, authState?.creds?.me?.id || 'sendRetryRequest')
+  }
+
+  // ── TC token helpers ──────────────────────────────────────────────────────
+
+  const reissueTcTokenAfterIdentityChange = (from) => {
+    void (async () => {
+      const normalizedJid = jidNormalizedUser(from)
+      const tcJid = await resolveTcTokenJid(normalizedJid, getLIDForPN)
+      const tcTokenData = await authState.keys.get('tctoken', [tcJid])
+      const senderTs = tcTokenData?.[tcJid]?.senderTimestamp
+      if (senderTs === null || senderTs === undefined || isTcTokenExpired(senderTs)) return
+      logger.debug({ jid: normalizedJid, senderTimestamp: senderTs }, 'identity changed, re-issuing tctoken')
+      const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+      const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
+      const issueJid = await resolveIssuanceJid(normalizedJid, issueToLid, getLIDForPN, getPNForLID)
+      const result = await issuePrivacyTokens([issueJid], senderTs)
+      await storeTcTokensFromIqResult({ result, fallbackJid: tcJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+    })().catch(err => logger.debug({ jid: from, err: err?.message }, 'failed to re-issue tctoken after identity change'))
+  }
+
+  const handlePrivacyTokenNotification = async (node) => {
+    const tokensNode = getBinaryNodeChild(node, 'tokens')
+    if (!tokensNode) return
+    const from = jidNormalizedUser(node.attrs.from)
+    const senderLid = node.attrs.sender_lid && isLidUser(jidNormalizedUser(node.attrs.sender_lid)) ? jidNormalizedUser(node.attrs.sender_lid) : undefined
+    const fallbackJid = senderLid ?? (await resolveTcTokenJid(from, getLIDForPN))
+    logger.debug({ from, storageJid: fallbackJid }, 'processing privacy token notification')
+    await storeTcTokensFromIqResult({ result: node, fallbackJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+  }
+
+  const tcTokenKnownJids = new Set()
+  const tcTokenIndexLoaded = (async () => {
+    try { const jids = await readTcTokenIndex(authState.keys); for (const jid of jids) tcTokenKnownJids.add(jid); if (tcTokenKnownJids.size > 0) logger.debug({ count: tcTokenKnownJids.size }, 'loaded tctoken index') }
+    catch (err) { logger.warn({ err: err?.message }, 'failed to load tctoken index') }
+  })()
+
+  let tcTokenIndexTimer
+  const flushTcTokenIndex = async () => {
+    if (tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined }
+    const write = await buildMergedTcTokenIndexWrite(authState.keys, tcTokenKnownJids)
+    return authState.keys.set({ tctoken: write })
+  }
+  const scheduleTcTokenIndexSave = () => {
+    if (tcTokenIndexTimer) clearTimeout(tcTokenIndexTimer)
+    tcTokenIndexTimer = setTimeout(() => { tcTokenIndexTimer = undefined; flushTcTokenIndex().catch(err => logger.warn({ err: err?.message }, 'failed to save tctoken index')) }, 5000)
+  }
+  const trackTcTokenJid = (jid) => { if (jid && jid !== TC_TOKEN_INDEX_KEY && !tcTokenKnownJids.has(jid)) { tcTokenKnownJids.add(jid); scheduleTcTokenIndexSave() } }
+
+  // ── Encrypt notification ──────────────────────────────────────────────────
+
+  const handleEncryptNotification = async (node) => {
+    const from = node.attrs.from
+    if (from === S_WHATSAPP_NET) {
+      const stanzaId = node.attrs.id
+      if (stanzaId && inFlightPreKeyLow.has(stanzaId)) return
+      const count = +getBinaryNodeChild(node, 'count').attrs.value
+      logger.debug({ count, shouldUploadMorePreKeys: count < MIN_PREKEY_COUNT }, 'recv pre-key count')
+      if (count < MIN_PREKEY_COUNT) {
+        if (stanzaId) inFlightPreKeyLow.add(stanzaId)
+        try { await uploadPreKeys() } finally { if (stanzaId) inFlightPreKeyLow.delete(stanzaId) }
+      }
+    } else {
+      const result = await handleIdentityChange(node, { meId: authState.creds.me?.id, meLid: authState.creds.me?.lid, validateSession: signalRepository.validateSession, assertSessions, debounceCache: identityAssertDebounce, logger, onBeforeSessionRefresh: reissueTcTokenAfterIdentityChange })
+      if (result.action === 'no_identity_node') logger.info({ node }, 'unknown encrypt notification')
+    }
+  }
+
+  // ── Group notification ────────────────────────────────────────────────────
+
+  const handleGroupNotification = (fullNode, child, msg) => {
+    const actingParticipantLid = fullNode.attrs.participant
+    const actingParticipantPn = fullNode.attrs.participant_pn
+    const actingParticipantUsername = fullNode.attrs.participant_username
+    const affectedParticipantLid = getBinaryNodeChild(child, 'participant')?.attrs?.jid || actingParticipantLid
+    const affectedParticipantPn = getBinaryNodeChild(child, 'participant')?.attrs?.phone_number || actingParticipantPn
+    switch (child?.tag) {
+      case 'create':
+        const metadata = extractGroupMetadata(child)
+        msg.messageStubType = WAMessageStubType.GROUP_CREATE
+        msg.messageStubParameters = [metadata.subject]
+        msg.key = { participant: metadata.owner, participantAlt: metadata.ownerPn }
+        ev.emit('chats.upsert', [{ id: metadata.id, name: metadata.subject, conversationTimestamp: metadata.creation }])
+        ev.emit('groups.upsert', [{ ...metadata, author: actingParticipantLid, authorPn: actingParticipantPn, authorUsername: actingParticipantUsername }])
+        break
+      case 'ephemeral':
+      case 'not_ephemeral':
+        msg.message = { protocolMessage: { type: proto.Message.ProtocolMessage.Type.EPHEMERAL_SETTING, ephemeralExpiration: +(child.attrs.expiration || 0) } }
+        break
+      case 'modify':
+        const modifiedParticipants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
+        msg.messageStubParameters = modifiedParticipants.map(a => JSON.stringify(a))
+        msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_CHANGE_NUMBER
+        break
+      case 'promote':
+      case 'demote':
+      case 'remove':
+      case 'add':
+      case 'leave':
+        msg.messageStubType = WAMessageStubType[`GROUP_PARTICIPANT_${child.tag.toUpperCase()}`]
+        const participants = getBinaryNodeChildren(child, 'participant').map(({ attrs }) => ({ id: attrs.jid, phoneNumber: isLidUser(attrs.jid) && isPnUser(attrs.phone_number) ? attrs.phone_number : undefined, lid: isPnUser(attrs.jid) && isLidUser(attrs.lid) ? attrs.lid : undefined, admin: attrs.type || null }))
+        if (participants.length === 1 && (areJidsSameUser(participants[0].id, actingParticipantLid) || areJidsSameUser(participants[0].id, actingParticipantPn)) && child.tag === 'remove') msg.messageStubType = WAMessageStubType.GROUP_PARTICIPANT_LEAVE
+        msg.messageStubParameters = participants.map(a => JSON.stringify(a))
+        break
+      case 'subject':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_SUBJECT
+        msg.messageStubParameters = [child.attrs.subject]
+        break
+      case 'description':
+        const description = getBinaryNodeChild(child, 'body')?.content?.toString()
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_DESCRIPTION
+        msg.messageStubParameters = description ? [description] : undefined
+        break
+      case 'announcement':
+      case 'not_announcement':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_ANNOUNCE
+        msg.messageStubParameters = [child.tag === 'announcement' ? 'on' : 'off']
+        break
+      case 'locked':
+      case 'unlocked':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_RESTRICT
+        msg.messageStubParameters = [child.tag === 'locked' ? 'on' : 'off']
+        break
+      case 'invite':
+        msg.messageStubType = WAMessageStubType.GROUP_CHANGE_INVITE_LINK
+        msg.messageStubParameters = [child.attrs.code]
+        break
+      case 'member_add_mode':
+        const addMode = child.content
+        if (addMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBER_ADD_MODE; msg.messageStubParameters = [addMode.toString()] }
+        break
+      case 'membership_approval_mode':
+        const approvalMode = getBinaryNodeChild(child, 'group_join')
+        if (approvalMode) { msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_MODE; msg.messageStubParameters = [approvalMode.attrs.state] }
+        break
+      case 'created_membership_requests':
+        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
+        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), 'created', child.attrs.request_method]
+        break
+      case 'revoked_membership_requests':
+        const isDenied = areJidsSameUser(affectedParticipantLid, actingParticipantLid)
+        msg.messageStubType = WAMessageStubType.GROUP_MEMBERSHIP_JOIN_APPROVAL_REQUEST_NON_ADMIN_ADD
+        msg.messageStubParameters = [JSON.stringify({ lid: affectedParticipantLid, pn: affectedParticipantPn }), isDenied ? 'revoked' : 'rejected']
+        break
+    }
+  }
+
+  // ── Devices notification ──────────────────────────────────────────────────
+
+  const handleDevicesNotification = async (node) => {
+    const [child] = getAllBinaryNodeChildren(node)
+    const from = jidNormalizedUser(node.attrs.from)
+    if (!child) { logger.debug({ from }, 'devices notification missing child, skipping'); return }
+    const tag = child.tag
+    const deviceHash = child.attrs.device_hash
+    const devices = getBinaryNodeChildren(child, 'device')
+    if (areJidsSameUser(from, authState.creds.me.id) || areJidsSameUser(from, authState.creds.me.lid)) logger.info({ deviceJids: devices.map(d => d.attrs.jid) }, 'got my own devices')
+    if (!devices.length) { logger.debug({ from, tag }, 'no devices in notification, skipping'); return }
+    const decoded = []
+    for (const d of devices) { const jid = d.attrs.jid; if (!jid) continue; const parts = jidDecode(jid); if (!parts) { logger.debug({ jid }, 'failed to decode device jid, skipping'); continue }; decoded.push({ jid, user: parts.user, server: parts.server, device: parts.device }) }
+    if (!decoded.length) return
+    await sock.devicesMutex.mutex(async () => {
+      const byUser = new Map()
+      for (const d of decoded) { const list = byUser.get(d.user) || []; list.push(d); byUser.set(d.user, list) }
+      for (const [user, entries] of byUser) {
+        if (tag === 'update') { logger.debug({ user }, `${user}'s device list updated, dropping cached devices`); await sock.userDevicesCache?.del(user); continue }
+        if (tag === 'remove') await signalRepository.deleteSession(entries.map(e => e.jid))
+        const existingCache = (await sock.userDevicesCache?.get(user)) || []
+        if (!existingCache.length) { logger.debug({ user, tag }, 'device list not cached, deferring to USync refresh'); continue }
+        const affected = new Set(entries.map(e => e.device))
+        let updatedDevices
+        switch (tag) {
+          case 'add': logger.info({ deviceHash, count: entries.length }, 'devices added'); updatedDevices = [...existingCache.filter(d => !affected.has(d.device)), ...entries.map(e => ({ user: e.user, server: e.server, device: e.device }))]; break
+          case 'remove': logger.info({ deviceHash, count: entries.length }, 'devices removed'); updatedDevices = existingCache.filter(d => !affected.has(d.device)); break
+          default: logger.debug({ tag }, 'unknown device list change tag'); continue
+        }
+        if (updatedDevices.length === 0) await sock.userDevicesCache?.del(user)
+        else await sock.userDevicesCache?.set(user, updatedDevices)
+      }
+    })
+  }
+
+  // ── processNotification ───────────────────────────────────────────────────
+
+  const processNotification = async (node) => {
+    const result = {}
+    const [child] = getAllBinaryNodeChildren(node)
+    const nodeType = node.attrs.type
+    const from = jidNormalizedUser(node.attrs.from)
+    switch (nodeType) {
+      case 'privacy_token': await handlePrivacyTokenNotification(node); break
+      case 'newsletter': await handleNewsletterNotification(node); break
+      case 'mex': await handleMexNotification(node); break
+      case 'w:gp2': handleGroupNotification(node, child, result); break
+      case 'mediaretry': ev.emit('messages.media-update', [decodeMediaRetryNode(node)]); break
+      case 'encrypt': await handleEncryptNotification(node); break
+      case 'devices':
+        try { await handleDevicesNotification(node) } catch (error) { logger.error({ error, node }, 'failed to handle devices notification') }
+        break
+      case 'server_sync':
+        const update = getBinaryNodeChild(node, 'collection')
+        if (update) await resyncAppState([update.attrs.name], false)
+        break
+      case 'picture':
+        const setPicture = getBinaryNodeChild(node, 'set')
+        const delPicture = getBinaryNodeChild(node, 'delete')
+        ev.emit('contacts.update', [{ id: jidNormalizedUser(node?.attrs?.from) || (setPicture || delPicture)?.attrs?.hash || '', imgUrl: setPicture ? 'changed' : 'removed' }])
+        if (isJidGroup(from)) {
+          const pictureNode = setPicture || delPicture
+          result.messageStubType = WAMessageStubType.GROUP_CHANGE_ICON
+          if (setPicture) result.messageStubParameters = [setPicture.attrs.id]
+          result.participant = pictureNode?.attrs.author
+          result.key = { ...(result.key || {}), participant: setPicture?.attrs.author }
+        }
+        break
+      case 'account_sync':
+        if (child.tag === 'disappearing_mode') {
+          const newDuration = +child.attrs.duration
+          logger.info({ newDuration }, 'updated account disappearing mode')
+          ev.emit('creds.update', { accountSettings: { ...authState.creds.accountSettings, defaultDisappearingMode: { ephemeralExpiration: newDuration, ephemeralSettingTimestamp: +child.attrs.t } } })
+        } else if (child.tag === 'blocklist') {
+          for (const { attrs } of getBinaryNodeChildren(child, 'item')) ev.emit('blocklist.update', { blocklist: [attrs.jid], type: attrs.action === 'block' ? 'add' : 'remove' })
+        }
+        break
+      case 'link_code_companion_reg':
+        const linkCodeNode = getBinaryNodeChild(node, 'link_code_companion_reg')
+        const ref = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_ref'))
+        const primaryIdentityPublicKey = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'primary_identity_pub'))
+        const primaryEphemeralWrapped = toRequiredBuffer(getBinaryNodeChildBuffer(linkCodeNode, 'link_code_pairing_wrapped_primary_ephemeral_pub'))
+        const codePairingPublicKey = await decipherLinkPublicKey(primaryEphemeralWrapped)
+        const companionSharedKey = Curve.sharedKey(authState.creds.pairingEphemeralKeyPair.private, codePairingPublicKey)
+        const random = randomBytes(32)
+        const linkCodeSalt = randomBytes(32)
+        const linkCodePairingExpanded = hkdf(companionSharedKey, 32, { salt: linkCodeSalt, info: 'link_code_pairing_key_bundle_encryption_key' })
+        const encryptPayload = Buffer.concat([Buffer.from(authState.creds.signedIdentityKey.public), primaryIdentityPublicKey, random])
+        const encryptIv = randomBytes(12)
+        const encrypted = aesEncryptGCM(encryptPayload, linkCodePairingExpanded, encryptIv, Buffer.alloc(0))
+        const encryptedPayload = Buffer.concat([linkCodeSalt, encryptIv, encrypted])
+        const identitySharedKey = Curve.sharedKey(authState.creds.signedIdentityKey.private, primaryIdentityPublicKey)
+        const identityPayload = Buffer.concat([companionSharedKey, identitySharedKey, random])
+        authState.creds.advSecretKey = Buffer.from(hkdf(identityPayload, 32, { info: 'adv_secret' })).toString('base64')
+        await query({ tag: 'iq', attrs: { to: S_WHATSAPP_NET, type: 'set', id: sock.generateMessageTag(), xmlns: 'md' }, content: [{ tag: 'link_code_companion_reg', attrs: { jid: authState.creds.me.id, stage: 'companion_finish' }, content: [{ tag: 'link_code_pairing_wrapped_key_bundle', attrs: {}, content: encryptedPayload }, { tag: 'companion_identity_public', attrs: {}, content: authState.creds.signedIdentityKey.public }, { tag: 'link_code_pairing_ref', attrs: {}, content: ref }] }] })
+        authState.creds.registered = true
+        ev.emit('creds.update', authState.creds)
+        break
+    }
+    if (Object.keys(result).length) return result
+  }
+
+  // ── Link pairing helpers ──────────────────────────────────────────────────
+
+  const decipherLinkPublicKey = async (data) => {
+    const buffer = toRequiredBuffer(data)
+    const salt = buffer.slice(0, 32)
+    const secretKey = await derivePairingCodeKey(authState.creds.pairingCode, salt)
+    const iv = buffer.slice(32, 48)
+    const payload = buffer.slice(48, 80)
+    return aesDecryptCTR(payload, secretKey, iv)
+  }
+
+  const toRequiredBuffer = (data) => {
+    if (data === undefined) throw new Boom('Invalid buffer', { statusCode: 400 })
+    return data instanceof Buffer ? data : Buffer.from(data)
+  }
+
+  // ── Retry helpers ─────────────────────────────────────────────────────────
+
+  const willSendMessageAgain = async (id, participant) => { const retryCount = (await msgRetryCache.get(`${id}:${participant}`)) || 0; return retryCount < maxMsgRetryCount }
+  const updateSendMessageAgainCount = async (id, participant) => { const key = `${id}:${participant}`; await msgRetryCache.set(key, ((await msgRetryCache.get(key)) || 0) + 1) }
+
+  const sendMessagesAgain = async (key, ids, retryNode, receiptNode) => {
+    const remoteJid = key.remoteJid
+    const participant = key.participant || remoteJid
+    const retryCount = +retryNode.attrs.count || 1
+    const msgs = []
+
+    for (const id of ids) {
+      let msg
+      if (messageRetryManager) { const cached = messageRetryManager.getRecentMessage(remoteJid, id); if (cached) { msg = cached.message; logger.debug({ jid: remoteJid, id }, 'found message in retry cache'); messageRetryManager.markRetrySuccess(id) } }
+      if (!msg) { msg = await getMessage({ ...key, id }); if (msg) { logger.debug({ jid: remoteJid, id }, 'found message via getMessage'); if (messageRetryManager) messageRetryManager.markRetrySuccess(id) } }
+      msgs.push(msg)
+    }
+
+    const sendToAll = !jidDecode(participant)?.device
+    const sessionId = signalRepository.jidToSignalProtocolAddress(participant)
+    let injectedFromBundle = false
+    const bundle = extractE2ESessionFromRetryReceipt(receiptNode)
+
+    if (bundle) {
+      try { await signalRepository.injectE2ESession({ jid: participant, session: bundle }); injectedFromBundle = true; logger.debug({ participant, retryCount }, 'injected session from retry receipt key bundle') }
+      catch (error) { logger.warn({ error, participant }, 'failed to inject session from retry receipt') }
+    }
+
+    if (!injectedFromBundle && typeof signalRepository.getSessionInfo === 'function') {
+      const receivedRegId = getBinaryNodeChildUInt(receiptNode, 'registration', 4)
+      if (typeof receivedRegId === 'number' && Number.isInteger(receivedRegId)) {
+        const info = await signalRepository.getSessionInfo(participant)
+        if (info && info.registrationId !== 0 && info.registrationId !== receivedRegId) { logger.info({ participant, stored: info.registrationId, received: receivedRegId }, 'reg id mismatch on retry without bundle, deleting session'); await authState.keys.set({ session: { [sessionId]: null } }) }
+      }
+    }
+
+    if (ids[0] && messageRetryManager && typeof messageRetryManager.saveBaseKey === 'function') {
+      const info = typeof signalRepository.getSessionInfo === 'function' ? await signalRepository.getSessionInfo(participant) : undefined
+      if (info) {
+        if (retryCount === 2) messageRetryManager.saveBaseKey(sessionId, ids[0], info.baseKey)
+        else if (retryCount > 2) {
+          if (messageRetryManager.hasSameBaseKey(sessionId, ids[0], info.baseKey)) { logger.warn({ participant, retryCount }, 'base key collision on retry, forcing fresh session'); await authState.keys.set({ session: { [sessionId]: null } }) }
+          messageRetryManager.deleteBaseKey(sessionId, ids[0])
+        }
+      }
+    }
+
+    let shouldRecreateSession = false, recreateReason = ''
+    if (enableAutoSessionRecreation && messageRetryManager && retryCount > 1 && !injectedFromBundle) {
+      try {
+        const hasSession = await signalRepository.validateSession(participant)
+        const result = messageRetryManager.shouldRecreateSession(participant, retryCount, hasSession.exists)
+        shouldRecreateSession = result.recreate; recreateReason = result.reason
+        if (shouldRecreateSession) { logger.debug({ participant, retryCount, reason: recreateReason }, 'recreating session for outgoing retry'); await authState.keys.set({ session: { [sessionId]: null } }) }
+      } catch (error) { logger.warn({ error, participant }, 'failed to check session recreation for outgoing retry') }
+    }
+
+    if (!injectedFromBundle) await assertSessions([participant], true)
+    if (isJidGroup(remoteJid)) await authState.keys.set({ 'sender-key-memory': { [remoteJid]: null } })
+    logger.debug({ participant, sendToAll, shouldRecreateSession, recreateReason, injectedFromBundle }, 'preparing retry recp')
+
+    for (const [i, msg] of msgs.entries()) {
+      if (!ids[i]) continue
+      if (msg && (await willSendMessageAgain(ids[i], participant))) {
+        await updateSendMessageAgainCount(ids[i], participant)
+        const msgRelayOpts = { messageId: ids[i] }
+        if (sendToAll) msgRelayOpts.useUserDevicesCache = false
+        else msgRelayOpts.participant = { jid: participant, count: +retryNode.attrs.count }
+        await relayMessage(key.remoteJid, msg, msgRelayOpts)
+      } else logger.debug({ jid: key.remoteJid, id: ids[i] }, 'recv retry request, but message not available')
+    }
+  }
+
+  // ── handleReceipt ─────────────────────────────────────────────────────────
+
+  const handleReceipt = async (node) => {
+    const { attrs, content } = node
+    const isLid = attrs.from.includes('lid')
+    const isNodeFromMe = areJidsSameUser(attrs.participant || attrs.from, isLid ? authState.creds.me?.lid : authState.creds.me?.id)
+    const remoteJid = !isNodeFromMe || isJidGroup(attrs.from) ? attrs.from : attrs.recipient
+    const fromMe = !attrs.recipient || ((attrs.type === 'retry' || attrs.type === 'sender') && isNodeFromMe)
+    const key = { remoteJid, id: '', fromMe, participant: attrs.participant }
+    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid }, 'ignoring receipt from jid'); await sendMessageAck(node); return }
+    const ids = [attrs.id]
+    if (Array.isArray(content)) ids.push(...getBinaryNodeChildren(content[0], 'item').map(i => i.attrs.id))
+    try {
+      await Promise.all([processingMutex.mutex(async () => {
+        const status = getStatusFromReceiptType(attrs.type)
+        if (typeof status !== 'undefined' && (status >= proto.WebMessageInfo.Status.SERVER_ACK || !isNodeFromMe)) {
+          if (isJidGroup(remoteJid) || isJidStatusBroadcast(remoteJid)) {
+            if (attrs.participant) {
+              const updateKey = status === proto.WebMessageInfo.Status.DELIVERY_ACK ? 'receiptTimestamp' : 'readTimestamp'
+              ev.emit('message-receipt.update', ids.map(id => ({ key: { ...key, id }, receipt: { userJid: jidNormalizedUser(attrs.participant), [updateKey]: +attrs.t } })))
+            }
+          } else ev.emit('messages.update', ids.map(id => ({ key: { ...key, id }, update: { status, messageTimestamp: toNumber(+(attrs.t ?? 0)) } })))
+        }
+        if (attrs.type === 'retry') {
+          key.participant = key.participant || attrs.from
+          const retryNode = getBinaryNodeChild(node, 'retry')
+          if (ids[0] && key.participant && (await willSendMessageAgain(ids[0], key.participant))) {
+            if (key.fromMe) {
+              try { await updateSendMessageAgainCount(ids[0], key.participant); logger.debug({ attrs, key }, 'recv retry request'); await sendMessagesAgain(key, ids, retryNode, node) }
+              catch (error) { logger.error({ key, ids, trace: error instanceof Error ? error.stack : 'Unknown error' }, 'error in sending message again') }
+            } else logger.info({ attrs, key }, 'recv retry for not fromMe message')
+          } else {
+            logger.info({ attrs, key, participant: key.participant }, 'retry limit exhausted - clearing broken session')
+            try {
+              await signalRepository.deleteSession([key.participant])
+              await msgRetryCache.del(`${ids[0]}:${key.participant}`)
+            } catch (err) { logger.error({ err, participant: key.participant }, 'failed to clear session/cache at retry exhaustion') }
+          }
+        }
+      })])
+    } finally { await sendMessageAck(node) }
+  }
+
+  // ── handleNotification ────────────────────────────────────────────────────
+
+  const handleNotification = async (node) => {
+    const remoteJid = node.attrs.from
+    if (shouldIgnoreJid(remoteJid) && remoteJid !== S_WHATSAPP_NET) { logger.debug({ remoteJid, id: node.attrs.id }, 'ignored notification'); await sendMessageAck(node); return }
+    try {
+      await Promise.all([notificationMutex.mutex(async () => {
+        const msg = await processNotification(node)
+        if (msg) {
+          const fromMe = areJidsSameUser(node.attrs.participant || remoteJid, authState.creds.me.id)
+          const { senderAlt: participantAlt, addressingMode } = extractAddressingContext(node)
+          msg.key = { remoteJid, fromMe, participant: node.attrs.participant, participantAlt, participantUsername: node.attrs.participant_username, addressingMode, id: node.attrs.id, ...(msg.key || {}) }
+          msg.participant ?? (msg.participant = node.attrs.participant)
+          msg.messageTimestamp = +node.attrs.t
+          await upsertMessage(proto.WebMessageInfo.fromObject(msg), 'append')
+        }
+      })])
+    } finally { await sendMessageAck(node) }
+  }
+
+  // ── handleMessage ─────────────────────────────────────────────────────────
+
+  const handleMessage = async (node) => {
+    if (shouldIgnoreJid(node.attrs.from) && node.attrs.from !== S_WHATSAPP_NET) { logger.debug({ key: node.attrs.key }, 'ignored message'); await sendMessageAck(node, NACK_REASONS.UnhandledError); return }
+
+    const encNode = getBinaryNodeChild(node, 'enc')
+    if (encNode && encNode.attrs.type === 'msmsg') {
+      const encIv = getBinaryNodeChildBuffer(encNode, 'enc_iv')
+      const encPayload = getBinaryNodeChildBuffer(encNode, 'enc_p') || encNode.content
+      if (!encIv || !encPayload) { logger.debug({ id: node.attrs.id, from: node.attrs.from, hasIv: !!encIv, hasPayload: !!encPayload }, 'msmsg missing enc_iv or enc_p, cannot decrypt'); await sendMessageAck(node); return }
+      try {
+        const messageSecret = authState.creds.myAppStateKeyId ? Buffer.from(authState.creds.myAppStateKeyId, 'base64') : undefined
+        if (!messageSecret) { logger.debug({ key: node.attrs.key }, 'no message secret for msmsg, skipping'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
+        const messageKey = { participant: node.attrs.participant || node.attrs.from, meId: authState.creds.me.id, meLid: authState.creds.me.lid, conversationJid: node.attrs.from, senderJid: node.attrs.participant, stanzaId: node.attrs.id, targetId: node.attrs.id }
+        const decrypted = await decryptMsmsgBotMessage(messageSecret, messageKey, { encPayload, encIv })
+        node.attrs._msmsgDecrypted = decodeDecryptedMsmsgMessage(decrypted)
+        logger.debug({ key: node.attrs.key }, 'decrypted msmsg bot message')
+      } catch (err) { logger.warn({ err, id: node.attrs.id }, 'failed to decrypt msmsg, falling back to nack'); await sendMessageAck(node, NACK_REASONS.MissingMessageSecret); return }
+    }
+
+    const { fullMessage: msg, category, author, decrypt } = decryptMessageNode(node, authState.creds.me.id, authState.creds.me.lid || '', signalRepository, logger)
+    const alt = msg.key.participantAlt || msg.key.remoteJidAlt
+    if (!!alt) {
+      const altServer = jidDecode(alt)?.server
+      const primaryJid = msg.key.participant || msg.key.remoteJid
+      if (altServer === 'lid') { if (!(await signalRepository.lidMapping.getPNForLID(alt))) { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: alt, pn: primaryJid }]); await signalRepository.migrateSession(primaryJid, alt) } }
+      else { await signalRepository.lidMapping.storeLIDPNMappings([{ lid: primaryJid, pn: alt }]); await signalRepository.migrateSession(alt, primaryJid) }
+    }
+
+    let acked = false
+    try {
+      await messageMutex.mutex(async () => {
+        await decrypt()
+        if (msg.key?.remoteJid && msg.key?.id && msg.message && messageRetryManager) messageRetryManager.addRecentMessage(msg.key.remoteJid, msg.key.id, msg.message)
+
+        if (msg.messageStubType === proto.WebMessageInfo.StubType.CIPHERTEXT && msg.category !== 'peer') {
+          if (msg?.messageStubParameters?.[0] === MISSING_KEYS_ERROR_TEXT) { acked = true; return sendMessageAck(node, NACK_REASONS.ParsingError) }
+          if (msg.messageStubParameters?.[0] === NO_MESSAGE_FOUND_ERROR_TEXT) {
+            const unavailableNode = getBinaryNodeChild(node, 'unavailable')
+            const unavailableType = unavailableNode?.attrs?.type
+            if (['bot_unavailable_fanout', 'hosted_unavailable_fanout', 'view_once_unavailable_fanout'].includes(unavailableType)) { logger.debug({ msgId: msg.key.id, unavailableType }, 'skipping placeholder resend for excluded unavailable type'); acked = true; return sendMessageAck(node) }
+            const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
+            if (messageAge > PLACEHOLDER_MAX_AGE_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge }, 'skipping placeholder resend for old message'); acked = true; return sendMessageAck(node) }
+            const cleanKey = { remoteJid: msg.key.remoteJid, fromMe: msg.key.fromMe, id: msg.key.id, participant: msg.key.participant }
+            const msgData = { key: msg.key, messageTimestamp: msg.messageTimestamp, pushName: msg.pushName, participant: msg.participant, verifiedBizName: msg.verifiedBizName }
+            requestPlaceholderResend(cleanKey, msgData).then(requestId => { if (requestId && requestId !== 'RESOLVED') { logger.debug({ msgId: msg.key.id, requestId }, 'requested placeholder resend for unavailable message'); ev.emit('messages.update', [{ key: msg.key, update: { messageStubParameters: [NO_MESSAGE_FOUND_ERROR_TEXT, requestId] } }]) } }).catch(err => logger.warn({ err, msgId: msg.key.id }, 'failed to request placeholder resend for unavailable message'))
+            acked = true; await sendMessageAck(node)
+          } else {
+            if ((msg.messageStubParameters?.[0] || '').includes('InvalidPreKeyId')) { logger.debug({ msgId: msg.key.id, remoteJid: msg.key.remoteJid }, 'skipping retry for InvalidPreKeyId, sender must re-establish session'); acked = true; return sendMessageAck(node, NACK_REASONS.UnhandledError) }
+            if (isJidStatusBroadcast(msg.key.remoteJid)) {
+              const messageAge = unixTimestampSeconds() - toNumber(msg.messageTimestamp)
+              if (messageAge > STATUS_EXPIRY_SECONDS) { logger.debug({ msgId: msg.key.id, messageAge, remoteJid: msg.key.remoteJid }, 'skipping retry for expired status message'); acked = true; return sendMessageAck(node) }
+            }
+            retryMutex.mutex(async () => {
+              try { if (!ws.isOpen) { logger.debug({ node }, 'Connection closed, skipping retry'); return }; await sendRetryRequest(node, true); if (retryRequestDelayMs) await delay(retryRequestDelayMs) }
+              catch (err) { logger.error({ err }, 'Retry mechanism failed'); try { await sendRetryRequest(node, !getBinaryNodeChild(node, 'enc')) } catch (retryErr) { logger.error({ retryErr }, 'Final retry attempt failed') } }
+              acked = true; await sendMessageAck(node, NACK_REASONS.UnhandledError)
+            })
+          }
+        } else {
+          if (messageRetryManager && msg.key.id) messageRetryManager.cancelPendingPhoneRequest(msg.key.id)
+          const isNewsletter = isJidNewsletter(msg.key.remoteJid)
+          if (!isNewsletter) {
+            let type = undefined, participant = msg.key.participant
+            if (category === 'peer') type = 'peer_msg'
+            else if (msg.key.fromMe) { type = 'sender'; if (isLidUser(msg.key.remoteJid) || isLidUser(msg.key.remoteJidAlt)) participant = author }
+            else if (!sendActiveReceipts) type = 'inactive'
+            acked = true; await sendReceipt(msg.key.remoteJid, participant, [msg.key.id], type)
+            if (getHistoryMsg(msg.message)) await sendReceipt(jidNormalizedUser(msg.key.remoteJid), undefined, [msg.key.id], 'hist_sync')
+          } else { acked = true; await sendMessageAck(node); logger.debug({ key: msg.key }, 'processed newsletter message without receipts') }
+        }
+
+        cleanMessage(msg, authState.creds.me.id, authState.creds.me.lid)
+
+        if (!msg.key.fromMe) {
+          try {
+            const info = extractReportingInfoFromStanza(node)
+            if (info) {
+              const senderJid = msg.key.participant || author || msg.key.remoteJid
+              const contentType = msg.message ? getContentType(msg.message) : undefined
+              config.reportingInfoStore.add(senderJid, { stanzaId: info.stanzaId, timestamp: info.timestamp || Number(msg.messageTimestamp) || 0, reportingTag: info.reportingTag, reportingToken: info.reportingToken, tokenVersion: info.tokenVersion, validationPolicy: info.validationPolicy, text: extractMessageText(msg), pushName: msg.pushName || node.attrs?.notify || '', messageType: contentType === 'conversation' || contentType === 'extendedTextMessage' ? 'text' : contentType || 'text', fromJid: senderJid })
+            }
+          } catch (storeErr) { logger.warn({ err: storeErr, key: msg.key }, 'failed to store reporting_tag') }
+        }
+
+        await upsertMessage(msg, node.attrs.offline ? 'append' : 'notify')
+      })
+    } catch (error) {
+      const isClosed = error?.message?.includes('Connection Closed') || error?.output?.statusCode === 428
+      if (isClosed) logger.debug({ msg: error?.message }, 'Connection closed while handling message')
+      else logger.error({ error, stack: error?.stack, msg: error?.message || String(error), node: binaryNodeToString(node) }, 'error in handling message')
+      if (!acked) await sendMessageAck(node, NACK_REASONS.UnhandledError).catch(ackErr => logger.error({ ackErr }, 'failed to ack message after error'))
+    }
+  }
+
+  // ── handleCall ────────────────────────────────────────────────────────────
+
+  const handleCall = async (node) => {
+    const { attrs } = node
+    const [infoChild] = getAllBinaryNodeChildren(node)
+    if (!infoChild) throw new Boom('Missing call info in call node')
+    const status = getCallStatusFromNode(infoChild)
+    const callId = infoChild.attrs['call-id']
+    const from = infoChild.attrs.from || infoChild.attrs['call-creator']
+    const call = { chatId: attrs.from, from, callerPn: infoChild.attrs['caller_pn'], id: callId, date: new Date(+attrs.t * 1000), offline: !!attrs.offline, status }
+    if (status === 'relaylatency') { const latencyValue = infoChild.attrs.latency || infoChild.attrs['latency_ms'] || infoChild.attrs['latency-ms']; const latencyMs = latencyValue ? Number(latencyValue) : undefined; if (Number.isFinite(latencyMs)) call.latencyMs = latencyMs }
+    if (status === 'offer') { call.isVideo = !!getBinaryNodeChild(infoChild, 'video'); call.isGroup = infoChild.attrs.type === 'group' || !!infoChild.attrs['group-jid']; call.groupJid = infoChild.attrs['group-jid']; await callOfferCache.set(call.id, call) }
+    const existingCall = await callOfferCache.get(call.id)
+    if (existingCall) { call.isVideo = existingCall.isVideo; call.isGroup = existingCall.isGroup; call.callerPn = call.callerPn || existingCall.callerPn }
+    if (['reject', 'accept', 'timeout', 'terminate'].includes(status)) await callOfferCache.del(call.id)
+    ev.emit('call', [call])
+    await sendMessageAck(node)
+  }
+
+  // ── handleBadAck ──────────────────────────────────────────────────────────
+
+  const handleBadAck = async ({ attrs }) => {
+    const key = { remoteJid: attrs.from, fromMe: true, id: attrs.id }
+    if (!attrs.error) return
+    const isReachoutTimelocked = attrs.error === String(NACK_REASONS.SenderReachoutTimelocked)
+    if (attrs.error === SERVER_ERROR_CODES.MessageAccountRestriction) {
+      logger.warn({ msgId: attrs.id, from: attrs.from }, 'error 463: account restricted or missing tctoken for contact')
+      const ackFrom = attrs.from
+      if (ackFrom && !inFlight463Recoveries.has(ackFrom)) {
+        inFlight463Recoveries.add(ackFrom)
+        void (async () => {
+          try {
+            const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+            const tcStorageJid = await resolveTcTokenJid(ackFrom, getLIDForPN)
+            const issueToLid = sock.serverProps?.lidTrustedTokenIssueToLid ?? false
+            const issueJid = await resolveIssuanceJid(ackFrom, issueToLid, getLIDForPN, getPNForLID)
+            const result = await issuePrivacyTokens([issueJid], unixTimestampSeconds())
+            await storeTcTokensFromIqResult({ result, fallbackJid: tcStorageJid, keys: authState.keys, getLIDForPN, onNewJidStored: trackTcTokenJid })
+            logger.debug({ from: ackFrom }, 'completed 463 token recovery issuance')
+            ev.emit('messages.update', [{ key, update: { status: WAMessageStatus.PENDING } }])
+          } catch (err) { logger.debug({ from: ackFrom, err: err?.message }, 'failed 463 token recovery issuance') }
+          finally { inFlight463Recoveries.delete(ackFrom) }
+        })()
+      }
+    } else if (attrs.error === SERVER_ERROR_CODES.SmaxInvalid) {
+      logger.warn({ msgId: attrs.id, from: attrs.from }, 'smax-invalid (479): stale device session or malformed addressing')
+    } else if (isReachoutTimelocked) {
+      await fetchAccountReachoutTimelock().catch(err => logger.warn({ err }, 'failed to fetch reachout timelock'))
+      logger.warn({ attrs }, 'received error in ack')
+    } else {
+      logger.warn({ attrs }, 'received error in ack')
+    }
+    ev.emit('messages.update', [{ key, update: { status: WAMessageStatus.ERROR, messageStubParameters: isReachoutTimelocked ? [attrs.error, ACCOUNT_RESTRICTED_TEXT] : [attrs.error] } }])
+  }
+
+  // ── Offline node processor ────────────────────────────────────────────────
+
+  const processNodeWithBuffer = async (node, identifier, exec) => { ev.buffer(); await exec(node, false).catch(err => onUnexpectedError(err, identifier)); ev.flush() }
+  const yieldToEventLoop = () => new Promise(resolve => setImmediate(resolve))
+
+  const makeOfflineNodeProcessor = () => {
+    const nodeProcessorMap = new Map([['message', handleMessage], ['call', handleCall], ['receipt', handleReceipt], ['notification', handleNotification]])
+    const nodes = []
+    let isProcessing = false
+    const enqueue = (type, node) => {
+      nodes.push({ type, node })
+      if (isProcessing) return
+      isProcessing = true;
+      (async () => {
+        let processedInBatch = 0
+        while (nodes.length && ws.isOpen) {
+          const { type, node } = nodes.shift()
+          const processor = nodeProcessorMap.get(type)
+          if (!processor) { onUnexpectedError(new Error(`unknown offline node type: ${type}`), 'processing offline node'); continue }
+          await processor(node).catch(err => onUnexpectedError(err, `processing offline ${type}`))
+          if (++processedInBatch >= 10) { processedInBatch = 0; await yieldToEventLoop() }
+        }
+        isProcessing = false
+      })().catch(error => onUnexpectedError(error, 'processing offline nodes'))
+    }
+    return { enqueue }
+  }
+
+  const offlineNodeProcessor = makeOfflineNodeProcessor()
+
+  const processNode = async (type, node, identifier, exec) => {
+    const from = node.attrs.from
+    if (from && from !== S_WHATSAPP_NET && shouldIgnoreJid(from)) { await sendMessageAck(node, type === 'message' ? NACK_REASONS.UnhandledError : undefined); return }
+    if (node.attrs.offline) offlineNodeProcessor.enqueue(type, node)
+    else await processNodeWithBuffer(node, identifier, exec)
+  }
+
+  // ── WS event bindings ─────────────────────────────────────────────────────
+
+  ws.on('CB:message', async (node) => { await processNode('message', node, 'processing message', handleMessage) })
+  ws.on('CB:call', async (node) => { await processNode('call', node, 'handling call', handleCall) })
+  ws.on('CB:receipt', async (node) => { await processNode('receipt', node, 'handling receipt', handleReceipt) })
+  ws.on('CB:notification', async (node) => { await processNode('notification', node, 'handling notification', handleNotification) })
+  ws.on('CB:ack,class:message', (node) => { handleBadAck(node).catch(error => onUnexpectedError(error, 'handling bad ack')) })
+
+  ev.on('call', async ([call]) => {
+    if (!call) return
+    if (call.status === 'timeout' || (call.status === 'offer' && call.isGroup)) {
+      const msg = { key: { remoteJid: call.chatId, id: call.id, fromMe: false }, messageTimestamp: unixTimestampSeconds(call.date) }
+      if (call.status === 'timeout') msg.messageStubType = call.isGroup ? (call.isVideo ? WAMessageStubType.CALL_MISSED_GROUP_VIDEO : WAMessageStubType.CALL_MISSED_GROUP_VOICE) : (call.isVideo ? WAMessageStubType.CALL_MISSED_VIDEO : WAMessageStubType.CALL_MISSED_VOICE)
+      else msg.message = { call: { callKey: Buffer.from(call.id) } }
+      await upsertMessage(proto.WebMessageInfo.fromObject(msg), call.offline ? 'append' : 'notify')
+    }
+  })
+
+  // ── TC token pruning ──────────────────────────────────────────────────────
+
+  let lastTcTokenPruneTs = 0
+  const pruneExpiredTcTokens = async () => {
+    try {
+      await tcTokenIndexLoaded
+      const persisted = await readTcTokenIndex(authState.keys)
+      const allJids = new Set([...tcTokenKnownJids, ...persisted])
+      if (!allJids.size) return
+      const jids = [...allJids]
+      const allTokens = await authState.keys.get('tctoken', jids)
+      const writes = {}, survivors = new Set()
+      let mutated = 0
+      for (const jid of jids) {
+        const entry = allTokens[jid]
+        if (!entry) { mutated++; continue }
+        const hasPeerToken = !!entry.token?.length
+        const peerTokenExpired = hasPeerToken && isTcTokenExpired(entry.timestamp)
+        const hasSenderTs = entry.senderTimestamp !== undefined
+        const senderTsExpired = hasSenderTs && isTcTokenExpired(entry.senderTimestamp)
+        const keepPeer = hasPeerToken && !peerTokenExpired
+        const keepSender = hasSenderTs && !senderTsExpired
+        if (!keepPeer && !keepSender) { writes[jid] = null; mutated++ }
+        else if (peerTokenExpired && keepSender) { writes[jid] = { token: Buffer.alloc(0), senderTimestamp: entry.senderTimestamp }; survivors.add(jid); mutated++ }
+        else survivors.add(jid)
+      }
+      if (mutated === 0) return
+      await authState.keys.set({ tctoken: { ...writes, [TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify([...survivors])) } } })
+      tcTokenKnownJids.clear(); for (const jid of survivors) tcTokenKnownJids.add(jid)
+      logger.debug({ mutated, remaining: survivors.size }, 'pruned expired tctokens')
+    } catch (err) { logger.warn({ err: err?.message }, 'failed to prune expired tctokens') }
+  }
+
+  ev.on('connection.update', ({ isOnline, connection }) => {
+    if (typeof isOnline !== 'undefined') { sendActiveReceipts = isOnline; logger.trace(`sendActiveReceipts set to "${sendActiveReceipts}"`) }
+    if (connection === 'close' && tcTokenIndexTimer) { clearTimeout(tcTokenIndexTimer); tcTokenIndexTimer = undefined; try { void Promise.resolve(flushTcTokenIndex()).catch(() => { }) } catch { } }
+    if (isOnline) { const now = Date.now(); if (now - lastTcTokenPruneTs >= 86_400_000) { lastTcTokenPruneTs = now; void pruneExpiredTcTokens() } }
+  })
+
+  registerSocketEndHandler(() => {
+    if (!config.msgRetryCounterCache && msgRetryCache.close) msgRetryCache.close()
+    if (!config.callOfferCache && callOfferCache.close) callOfferCache.close()
+    identityAssertDebounce.close()
+    sendActiveReceipts = false
+  })
+
+  return { ...sock, sendMessageAck, sendRetryRequest, rejectCall, offerCall, fetchMessageHistory, requestPlaceholderResend, requestContactRefresh, messageRetryManager, tcTokenIndexLoaded }
 }