@omnizap-system/omnizap 2.5.12

package/app/connection/socketController.js

@@ -0,0 +1,2243 @@
+import makeWASocket, { DisconnectReason, Browsers, getAggregateVotesInPollMessage, areJidsSameUser, WAMessageStatus, WAMessageStubType, delayCancellable, getStatusFromReceiptType, promiseTimeout } from '@whiskeysockets/baileys';
+
+import NodeCache from 'node-cache';
+import { parseEnvBool, parseEnvCsv, parseEnvInt, resolveBaileysVersion, resolveAddressingModeFromMessageKey, normalizeAddressingMode, normalizePnToJid, normalizeWAPresence, baileysConnectionLogger as logger, baileysSocketLogger } from '../config/index.js';
+
+import { Boom } from '@hapi/boom';
+import qrcode from 'qrcode-terminal';
+import path from 'node:path';
+
+import { handleMessages } from '../controllers/messageController.js';
+import { syncNewsBroadcastService } from '../services/messaging/newsBroadcastService.js';
+import { setActiveSocket as storeActiveSocket, runActiveSocketMethod, isSocketOpen } from '../config/index.js';
+import { recordError, recordMessagesUpsert } from '../observability/metrics.js';
+import { resolveCaptchaByReaction } from '../services/messaging/captchaService.js';
+
+import { handleGroupUpdate as handleGroupParticipantsEvent, handleGroupJoinRequest } from '../modules/adminModule/groupEventHandlers.js';
+
+import { dbConfig, executeQuery, findBy, findById, pool, remove } from '../../database/index.js';
+import { extractSenderInfoFromMessage, primeLidCache, resolveUserIdCached, isLidUserId, isWhatsAppUserId } from '../config/index.js';
+import { queueBaileysEventInsert, queueChatUpdate, queueLidUpdate, queueMessageInsert } from '../services/infra/dbWriteQueue.js';
+import { buildGroupMetadataFromGroup, buildGroupMetadataFromUpdate, upsertGroupMetadata, parseParticipantsFromDb } from '../services/group/groupMetadataService.js';
+import { buildMessageData } from '../configParts/messagePersistenceService.js';
+import { useDbAuthState } from './baileysDbAuthState.js';
+
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Indica se o ambiente de execução é de produção.
+ * @type {boolean}
+ */
+const IS_PRODUCTION =
+  String(process.env.NODE_ENV || '')
+    .trim()
+    .toLowerCase() === 'production';
+/**
+ * Tempo de vida (TTL) em segundos para o cache de retentativa de mensagem do Baileys.
+ * @type {number}
+ */
+const MSG_RETRY_CACHE_TTL_SECONDS = parseEnvInt(process.env.BAILEYS_MSG_RETRY_CACHE_TTL_SECONDS, 600, 60, 24 * 60 * 60);
+/**
+ * Período de verificação em segundos para o cache de retentativa de mensagem do Baileys.
+ * @type {number}
+ */
+const MSG_RETRY_CACHE_CHECKPERIOD_SECONDS = parseEnvInt(process.env.BAILEYS_MSG_RETRY_CACHE_CHECKPERIOD_SECONDS, 120, 30, 3600);
+/**
+ * Habilita ou desabilita o log de eventos do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_EVENT_LOG_ENABLED = parseEnvBool(process.env.BAILEYS_EVENT_LOG_ENABLED, !IS_PRODUCTION);
+/**
+ * Tempo em milissegundos para resetar a contagem de tentativas de reconexão do Baileys.
+ * @type {number}
+ */
+const BAILEYS_RECONNECT_ATTEMPT_RESET_MS = parseEnvInt(process.env.BAILEYS_RECONNECT_ATTEMPT_RESET_MS, 10 * 60 * 1000, 60 * 1000, 24 * 60 * 60 * 1000);
+/**
+ * Habilita ou desabilita a sincronização de grupos na conexão.
+ * @type {boolean}
+ */
+const GROUP_SYNC_ON_CONNECT = parseEnvBool(process.env.GROUP_SYNC_ON_CONNECT, true);
+/**
+ * Tempo limite em milissegundos para a sincronização de grupos.
+ * @type {number}
+ */
+const GROUP_SYNC_TIMEOUT_MS = parseEnvInt(process.env.GROUP_SYNC_TIMEOUT_MS, 30 * 1000, 5 * 1000, 120 * 1000);
+/**
+ * Número máximo de grupos a serem sincronizados.
+ * @type {number}
+ */
+const GROUP_SYNC_MAX_GROUPS = parseEnvInt(process.env.GROUP_SYNC_MAX_GROUPS, 0, 0, 10_000);
+/**
+ * Tamanho do lote para a sincronização de grupos.
+ * @type {number}
+ */
+const GROUP_SYNC_BATCH_SIZE = parseEnvInt(process.env.GROUP_SYNC_BATCH_SIZE, 50, 1, 1000);
+/**
+ * Habilita ou desabilita a rejeição automática de chamadas do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_AUTO_REJECT_CALLS = parseEnvBool(process.env.BAILEYS_AUTO_REJECT_CALLS, true);
+/**
+ * Habilita ou desabilita a recriação automática de sessão do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_ENABLE_AUTO_SESSION_RECREATION = parseEnvBool(process.env.BAILEYS_ENABLE_AUTO_SESSION_RECREATION, true);
+/**
+ * Habilita ou desabilita o cache de mensagens recentes do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_ENABLE_RECENT_MESSAGE_CACHE = parseEnvBool(process.env.BAILEYS_ENABLE_RECENT_MESSAGE_CACHE, true);
+/**
+ * Habilita ou desabilita a geração de pré-visualizações de link de alta qualidade do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_GENERATE_HIGH_QUALITY_LINK_PREVIEW = parseEnvBool(process.env.BAILEYS_GENERATE_HIGH_QUALITY_LINK_PREVIEW, false);
+/**
+ * Habilita ou desabilita o patch de mensagens antes do envio.
+ * @type {boolean}
+ */
+const BAILEYS_PATCH_MESSAGE_BEFORE_SENDING = parseEnvBool(process.env.BAILEYS_PATCH_MESSAGE_BEFORE_SENDING, true);
+/**
+ * Tempo de vida (TTL) em segundos para o cache de dispositivos de usuário do Baileys.
+ * @type {number}
+ */
+const BAILEYS_USER_DEVICES_CACHE_TTL_SECONDS = parseEnvInt(process.env.BAILEYS_USER_DEVICES_CACHE_TTL_SECONDS, 300, 30, 24 * 60 * 60);
+/**
+ * Período de verificação em segundos para o cache de dispositivos de usuário do Baileys.
+ * @type {number}
+ */
+const BAILEYS_USER_DEVICES_CACHE_CHECKPERIOD_SECONDS = parseEnvInt(process.env.BAILEYS_USER_DEVICES_CACHE_CHECKPERIOD_SECONDS, 60, 15, 3600);
+/**
+ * Tempo de vida (TTL) em segundos para o cache de mídia do Baileys.
+ * @type {number}
+ */
+const BAILEYS_MEDIA_CACHE_TTL_SECONDS = parseEnvInt(process.env.BAILEYS_MEDIA_CACHE_TTL_SECONDS, 3600, 60, 7 * 24 * 60 * 60);
+/**
+ * Período de verificação em segundos para o cache de mídia do Baileys.
+ * @type {number}
+ */
+const BAILEYS_MEDIA_CACHE_CHECKPERIOD_SECONDS = parseEnvInt(process.env.BAILEYS_MEDIA_CACHE_CHECKPERIOD_SECONDS, 300, 30, 3600);
+/**
+ * Tempo de vida (TTL) em segundos para o cache de metadados de grupo do Baileys.
+ * @type {number}
+ */
+const BAILEYS_GROUP_METADATA_CACHE_TTL_SECONDS = parseEnvInt(process.env.BAILEYS_GROUP_METADATA_CACHE_TTL_SECONDS, 120, 10, 3600);
+/**
+ * Período de verificação em segundos para o cache de metadados de grupo do Baileys.
+ * @type {number}
+ */
+const BAILEYS_GROUP_METADATA_CACHE_CHECKPERIOD_SECONDS = parseEnvInt(process.env.BAILEYS_GROUP_METADATA_CACHE_CHECKPERIOD_SECONDS, 60, 10, 1800);
+/**
+ * Identificador lógico da sessão de autenticação do Baileys no MySQL.
+ * Permite isolar múltiplas sessões no mesmo banco.
+ * @type {string}
+ */
+const BAILEYS_AUTH_SESSION_ID = (() => {
+  const raw = String(process.env.BAILEYS_AUTH_SESSION_ID || '').trim();
+  return raw || 'default';
+})();
+/**
+ * Habilita bootstrap inicial do auth state no MySQL usando os arquivos locais legados.
+ * @type {boolean}
+ */
+const BAILEYS_AUTH_BOOTSTRAP_FROM_FILES = parseEnvBool(process.env.BAILEYS_AUTH_BOOTSTRAP_FROM_FILES, true);
+/**
+ * Habilita lock de escritor único para evitar múltiplos processos escrevendo a mesma sessão.
+ * @type {boolean}
+ */
+const BAILEYS_SINGLE_WRITER_LOCK_ENABLED = parseEnvBool(process.env.BAILEYS_SINGLE_WRITER_LOCK_ENABLED, true);
+/**
+ * Timeout (segundos) para tentar adquirir lock de escritor único no MySQL.
+ * @type {number}
+ */
+const BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS = parseEnvInt(process.env.BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS, 2, 0, 60);
+/**
+ * Atraso para nova tentativa quando lock de escritor único estiver ocupado.
+ * @type {number}
+ */
+const BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS = parseEnvInt(process.env.BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS, 15_000, 1_000, 300_000);
+/**
+ * Nome do lock de escritor único usado no MySQL.
+ * @type {string}
+ */
+const BAILEYS_SINGLE_WRITER_LOCK_NAME = (() => {
+  const raw = String(process.env.BAILEYS_SINGLE_WRITER_LOCK_NAME || '').trim();
+  if (raw) return raw;
+  const dbLabel = String(dbConfig?.database || 'db').replace(/[^a-zA-Z0-9:_-]+/g, '_');
+  return `omnizap:baileys:writer:${dbLabel}`;
+})();
+/**
+ * Habilita ou desabilita o diário de eventos do Baileys.
+ * @type {boolean}
+ */
+const BAILEYS_EVENT_JOURNAL_ENABLED = parseEnvBool(process.env.BAILEYS_EVENT_JOURNAL_ENABLED, false);
+/**
+ * Lista de eventos padrão para o diário de eventos do Baileys.
+ * @type {string[]}
+ */
+const DEFAULT_BAILEYS_EVENT_JOURNAL_EVENTS = ['connection.update', 'messages.upsert', 'messages.update', 'messages.delete', 'messages.reaction', 'message-receipt.update', 'chats.upsert', 'chats.update', 'chats.delete', 'groups.upsert', 'groups.update', 'group-participants.update', 'group.join-request', 'lid-mapping.update'];
+/**
+ * Lista de eventos configurados para o diário de eventos do Baileys, obtidos do ambiente.
+ * @type {string[]}
+ */
+const BAILEYS_EVENT_JOURNAL_EVENT_LIST = parseEnvCsv(process.env.BAILEYS_EVENT_JOURNAL_EVENTS, DEFAULT_BAILEYS_EVENT_JOURNAL_EVENTS);
+/**
+ * Indica se todos os eventos do Baileys devem ser registrados no diário.
+ * @type {boolean}
+ */
+const BAILEYS_EVENT_JOURNAL_ALL_EVENTS = BAILEYS_EVENT_JOURNAL_EVENT_LIST.includes('*');
+/**
+ * Conjunto de eventos do Baileys a serem registrados no diário.
+ * @type {Set<string>}
+ */
+const BAILEYS_EVENT_JOURNAL_EVENTS = new Set(BAILEYS_EVENT_JOURNAL_EVENT_LIST.filter((eventName) => eventName !== '*'));
+/**
+ * Conjunto de tipos de recibo que não mapeiam diretamente para status no Baileys.
+ * @type {Set<string>}
+ */
+const MESSAGE_RECEIPT_TYPES_WITHOUT_STATUS = new Set(['hist_sync', 'peer_msg', 'inactive']);
+/**
+ * Mapeia códigos de status de mensagem do Baileys para seus nomes.
+ * @type {Map<number, string>}
+ */
+const MESSAGE_STATUS_CODE_TO_NAME = new Map(
+  Object.entries(WAMessageStatus)
+    .filter(([, value]) => typeof value === 'number')
+    .map(([name, value]) => [value, name]),
+);
+/**
+ * Mapeia códigos de tipo de stub de mensagem do Baileys para seus nomes.
+ * @type {Map<number, string>}
+ */
+const MESSAGE_STUB_CODE_TO_NAME = new Map(
+  Object.entries(WAMessageStubType)
+    .filter(([, value]) => typeof value === 'number')
+    .map(([name, value]) => [value, name]),
+);
+
+/**
+ * Normaliza o status de uma mensagem do Baileys.
+ * @param {string | number} status - O código de status da mensagem.
+ * @returns {{code: number, name: string | null} | null} Objeto contendo o código e o nome do status, ou null se inválido.
+ */
+const normalizeMessageStatus = (status) => {
+  const statusCode = Number(status);
+  if (!Number.isFinite(statusCode)) return null;
+  return {
+    code: statusCode,
+    name: MESSAGE_STATUS_CODE_TO_NAME.get(statusCode) || null,
+  };
+};
+
+/**
+ * Normaliza o tipo de stub de uma mensagem do Baileys.
+ * @param {string | number} stubType - O código do tipo de stub da mensagem.
+ * @returns {{code: number, name: string | null} | null} Objeto contendo o código e o nome do tipo de stub, ou null se inválido.
+ */
+const normalizeMessageStubType = (stubType) => {
+  const stubTypeCode = Number(stubType);
+  if (!Number.isFinite(stubTypeCode)) return null;
+  return {
+    code: stubTypeCode,
+    name: MESSAGE_STUB_CODE_TO_NAME.get(stubTypeCode) || null,
+  };
+};
+
+/**
+ * Normaliza o tipo de recibo de mensagem.
+ * @param {string | undefined} receiptType - O tipo de recibo da mensagem.
+ * @returns {string | undefined} O tipo de recibo normalizado, ou undefined se inválido.
+ */
+const normalizeMessageReceiptType = (receiptType) => {
+  if (receiptType === undefined) return undefined;
+  if (typeof receiptType !== 'string') return undefined;
+  const normalizedType = receiptType.trim();
+  if (!normalizedType) return undefined;
+  if (getStatusFromReceiptType(normalizedType) !== undefined) return normalizedType;
+  return MESSAGE_RECEIPT_TYPES_WITHOUT_STATUS.has(normalizedType) ? normalizedType : undefined;
+};
+
+/**
+ * Instância ativa do socket do WhatsApp.
+ * @type {import('@whiskeysockets/baileys').WASocket | null}
+ */
+let activeSocket = null;
+/**
+ * Contador de tentativas de conexão.
+ * @type {number}
+ */
+let connectionAttempts = 0;
+/**
+ * Timestamp do início da janela de reconexão.
+ * @type {number}
+ */
+let reconnectWindowStartedAt = 0;
+/**
+ * Cache para contadores de retentativa de mensagens.
+ * @type {NodeCache}
+ */
+const msgRetryCounterCache = new NodeCache({
+  stdTTL: MSG_RETRY_CACHE_TTL_SECONDS,
+  checkperiod: MSG_RETRY_CACHE_CHECKPERIOD_SECONDS,
+  useClones: false,
+});
+/**
+ * Backend de cache para informações de dispositivos de usuário.
+ * @type {NodeCache}
+ */
+const userDevicesCacheBackend = new NodeCache({
+  stdTTL: BAILEYS_USER_DEVICES_CACHE_TTL_SECONDS,
+  checkperiod: BAILEYS_USER_DEVICES_CACHE_CHECKPERIOD_SECONDS,
+  useClones: false,
+});
+/**
+ * Backend de cache para mídia.
+ * @type {NodeCache}
+ */
+const mediaCacheBackend = new NodeCache({
+  stdTTL: BAILEYS_MEDIA_CACHE_TTL_SECONDS,
+  checkperiod: BAILEYS_MEDIA_CACHE_CHECKPERIOD_SECONDS,
+  useClones: false,
+});
+/**
+ * Cache para metadados de grupos.
+ * @type {NodeCache}
+ */
+const groupMetadataCache = new NodeCache({
+  stdTTL: BAILEYS_GROUP_METADATA_CACHE_TTL_SECONDS,
+  checkperiod: BAILEYS_GROUP_METADATA_CACHE_CHECKPERIOD_SECONDS,
+  useClones: false,
+});
+/**
+ * Número máximo de tentativas de conexão antes de entrar em um período de espera.
+ * @type {number}
+ */
+const MAX_CONNECTION_ATTEMPTS = 5;
+/**
+ * Atraso inicial em milissegundos para a primeira tentativa de reconexão.
+ * @type {number}
+ */
+const INITIAL_RECONNECT_DELAY = 3000;
+/**
+ * Timeout para reconexão.
+ * @type {ReturnType<typeof delayCancellable> | null}
+ */
+let reconnectTimeout = null;
+/**
+ * Promessa de conexão ativa.
+ * @type {Promise<void> | null}
+ */
+let connectPromise = null;
+/**
+ * Geração atual do socket (incrementado a cada nova conexão).
+ * @type {number}
+ */
+let socketGeneration = 0;
+/**
+ * Conexão MySQL dedicada para manter lock de escritor único do Baileys.
+ * @type {import('mysql2/promise').PoolConnection | null}
+ */
+let baileysWriterLockConnection = null;
+/**
+ * Nomes de todos os eventos do Baileys que são monitorados.
+ * @type {string[]}
+ */
+const BAILEYS_EVENT_NAMES = ['connection.update', 'creds.update', 'messaging-history.set', 'chats.upsert', 'chats.update', 'lid-mapping.update', 'chats.delete', 'presence.update', 'contacts.upsert', 'contacts.update', 'messages.delete', 'messages.update', 'messages.media-update', 'messages.upsert', 'messages.reaction', 'message-receipt.update', 'groups.upsert', 'groups.update', 'group-participants.update', 'group.join-request', 'group.member-tag.update', 'blocklist.set', 'blocklist.update', 'call', 'labels.edit', 'labels.association', 'newsletter.reaction', 'newsletter.view', 'newsletter-participants.update', 'newsletter-settings.update', 'chats.lock', 'settings.update'];
+/**
+ * Conjunto de eventos do Baileys que possuem lógica de log interna.
+ * @type {Set<string>}
+ */
+const BAILEYS_EVENTS_WITH_INTERNAL_LOG = new Set(['creds.update', 'connection.update', 'messages.upsert', 'messages.update', 'messages.media-update', 'message-receipt.update', 'groups.update', 'group-participants.update']);
+/**
+ * Conjunto de eventos do Baileys que são considerados "barulhentos" em produção e podem ser desabilitados.
+ * @type {Set<string>}
+ */
+const BAILEYS_NOISY_EVENTS_IN_PRODUCTION = new Set(['presence.update']);
+
+/**
+ * Cria um adaptador de armazenamento de cache simples para um NodeCache.
+ * @param {NodeCache} cache - Instância do NodeCache.
+ * @returns {{get: Function, set: Function, del: Function, flushAll: Function}} Adaptador de cache.
+ */
+const createCacheStoreAdapter = (cache) => ({
+  get: (key) => cache.get(key),
+  set: (key, value) => cache.set(key, value),
+  del: (key) => cache.del(key),
+  flushAll: () => cache.flushAll(),
+});
+
+/**
+ * Cria um adaptador de armazenamento de cache estendido com métodos multi para um NodeCache.
+ * @param {NodeCache} cache - Instância do NodeCache.
+ * @returns {{get: Function, set: Function, del: Function, flushAll: Function, mget: Function, mset: Function, mdel: Function}} Adaptador de cache estendido.
+ */
+const createExtendedCacheStoreAdapter = (cache) => ({
+  ...createCacheStoreAdapter(cache),
+  mget: (keys) => cache.mget(keys),
+  mset: (entries) => {
+    if (!Array.isArray(entries) || entries.length === 0) return;
+    cache.mset(
+      entries
+        .filter((entry) => entry && typeof entry.key === 'string')
+        .map((entry) => ({
+          key: entry.key,
+          val: entry.value,
+        })),
+    );
+  },
+  mdel: (keys) => cache.del(keys),
+});
+
+/**
+ * Cache para informações de dispositivos de usuário.
+ * @type {ReturnType<typeof createExtendedCacheStoreAdapter>}
+ */
+const userDevicesCache = createExtendedCacheStoreAdapter(userDevicesCacheBackend);
+/**
+ * Cache para mídia.
+ * @type {ReturnType<typeof createCacheStoreAdapter>}
+ */
+const mediaCache = createCacheStoreAdapter(mediaCacheBackend);
+
+/**
+ * Verifica se um valor é um objeto "simples" (plain object).
+ * @param {unknown} value - O valor a ser verificado.
+ * @returns {boolean} True se for um objeto simples, false caso contrário.
+ */
+const isPlainObject = (value) => Object.prototype.toString.call(value) === '[object Object]';
+
+/**
+ * Sanitiza o payload de uma mensagem removendo funções, valores undefined e referências circulares.
+ * @param {any} value - O payload da mensagem a ser sanitizado.
+ * @param {WeakSet<object>} [seen=new WeakSet()] - Conjunto de objetos já vistos para evitar referências circulares.
+ * @returns {any} O payload sanitizado.
+ */
+const sanitizeMessagePayload = (value, seen = new WeakSet()) => {
+  if (value === undefined || typeof value === 'function') return undefined;
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'bigint') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array || value instanceof Date) return value;
+  if (typeof value !== 'object') return value;
+  if (seen.has(value)) return undefined;
+
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const sanitizedArray = [];
+    for (const item of value) {
+      const sanitized = sanitizeMessagePayload(item, seen);
+      if (typeof sanitized !== 'undefined') sanitizedArray.push(sanitized);
+    }
+    return sanitizedArray;
+  }
+
+  if (!isPlainObject(value)) return value;
+
+  const sanitizedObject = {};
+  for (const [key, item] of Object.entries(value)) {
+    const sanitized = sanitizeMessagePayload(item, seen);
+    if (typeof sanitized !== 'undefined') {
+      sanitizedObject[key] = sanitized;
+    }
+  }
+
+  return sanitizedObject;
+};
+
+/**
+ * Aplica saneamento a uma mensagem antes de enviá-la, se a funcionalidade estiver habilitada.
+ * @async
+ * @param {any} message - A mensagem a ser potencialmente sanitizada.
+ * @returns {Promise<any>} A mensagem sanitizada ou original.
+ */
+const patchMessageBeforeSending = async (message) => {
+  if (!BAILEYS_PATCH_MESSAGE_BEFORE_SENDING) return message;
+  try {
+    const sanitized = sanitizeMessagePayload(message);
+    if (!sanitized || typeof sanitized !== 'object') return message;
+    return sanitized;
+  } catch (error) {
+    logger.warn('Falha ao sanitizar payload de mensagem antes do envio. Usando payload original.', {
+      action: 'patch_message_before_sending_error',
+      error: error?.message,
+    });
+    return message;
+  }
+};
+
+/**
+ * Constrói uma lista de participantes de grupo a partir de dados brutos do DB.
+ * @param {any} participantsRaw - Dados brutos dos participantes.
+ * @returns {Array<{id: string, admin?: 'admin' | 'superadmin'} | null>} Lista de participantes formatada.
+ */
+const buildCachedParticipants = (participantsRaw) => {
+  const participants = parseParticipantsFromDb(participantsRaw);
+  if (!Array.isArray(participants) || participants.length === 0) return [];
+  return participants
+    .map((entry) => {
+      const id = entry?.id || entry?.jid || entry?.lid || null;
+      if (!id) return null;
+      const admin = entry?.admin === 'admin' || entry?.admin === 'superadmin' ? entry.admin : entry?.isAdmin ? 'admin' : undefined;
+      return admin ? { id, admin } : { id };
+    })
+    .filter(Boolean);
+};
+
+/**
+ * Resolve metadados de grupo do cache local ou do banco de dados.
+ * @async
+ * @param {string} jid - O JID do grupo.
+ * @returns {Promise<object | undefined>} Metadados do grupo ou undefined.
+ */
+const resolveCachedGroupMetadata = async (jid) => {
+  if (!jid || typeof jid !== 'string' || !jid.endsWith('@g.us')) return undefined;
+
+  const cached = groupMetadataCache.get(jid);
+  if (cached) return cached;
+
+  try {
+    const row = await findById('groups_metadata', jid);
+    const data = Array.isArray(row) ? row[0] : row;
+    if (!data) return undefined;
+
+    const participants = buildCachedParticipants(data.participants || data.participants_json);
+    if (participants.length === 0) return undefined;
+
+    const metadata = {
+      id: data.id || jid,
+      subject: data.subject || data.name || '',
+      desc: data.description || data.desc || '',
+      owner: data.owner_jid || data.owner || undefined,
+      creation: Number.isFinite(Number(data.creation)) ? Number(data.creation) : undefined,
+      participants,
+      addressingMode: normalizeAddressingMode(data.addressing_mode || data.addressingMode),
+      ephemeralDuration: Number.isFinite(Number(data.ephemeral_duration ?? data.ephemeralDuration)) ? Number(data.ephemeral_duration ?? data.ephemeralDuration) : undefined,
+    };
+
+    groupMetadataCache.set(jid, metadata);
+    return metadata;
+  } catch (error) {
+    logger.debug('Falha ao resolver metadados de grupo do cache local.', {
+      action: 'cached_group_metadata_lookup_error',
+      jid,
+      error: error?.message,
+    });
+    return undefined;
+  }
+};
+
+/**
+ * Invalida o cache de metadados para um grupo específico.
+ * @param {string} groupId - O ID do grupo a ser invalidado no cache.
+ * @returns {void}
+ */
+const invalidateCachedGroupMetadata = (groupId) => {
+  if (!groupId || typeof groupId !== 'string') return;
+  groupMetadataCache.del(groupId);
+};
+
+/**
+ * Gera um resumo conciso do payload de um evento do Baileys para fins de log e persistência.
+ * @param {string} eventName - O nome do evento do Baileys.
+ * @param {any} payload - O payload do evento.
+ * @returns {object} Um objeto resumindo o payload.
+ */
+const summarizeBaileysEventPayload = (eventName, payload) => {
+  if (payload === null) return { payloadType: 'null' };
+  if (payload === undefined) return { payloadType: 'undefined' };
+  if (Buffer.isBuffer(payload)) {
+    return { payloadType: 'buffer', bytes: payload.length };
+  }
+
+  if (Array.isArray(payload)) {
+    const summary = { payloadType: 'array', items: payload.length };
+    if (payload.length > 0 && payload[0] && typeof payload[0] === 'object') {
+      summary.sampleKeys = Object.keys(payload[0]).slice(0, 6);
+    }
+    return summary;
+  }
+
+  if (typeof payload !== 'object') {
+    if (typeof payload === 'string') {
+      return { payloadType: 'string', length: payload.length };
+    }
+    return { payloadType: typeof payload, value: payload };
+  }
+
+  const summary = { payloadType: 'object', keys: Object.keys(payload).slice(0, 10) };
+
+  switch (eventName) {
+    case 'messaging-history.set':
+      summary.chats = Array.isArray(payload.chats) ? payload.chats.length : 0;
+      summary.contacts = Array.isArray(payload.contacts) ? payload.contacts.length : 0;
+      summary.messages = Array.isArray(payload.messages) ? payload.messages.length : 0;
+      summary.isLatest = payload.isLatest ?? null;
+      summary.progress = payload.progress ?? null;
+      summary.syncType = payload.syncType ?? null;
+      break;
+    case 'presence.update':
+      summary.id = payload.id ?? null;
+      summary.presencesCount = payload.presences ? Object.keys(payload.presences).length : 0;
+      break;
+    case 'chats.lock':
+      summary.id = payload.id ?? null;
+      summary.locked = payload.locked ?? null;
+      break;
+    case 'settings.update':
+      summary.setting = payload.setting ?? null;
+      break;
+    case 'messages.delete':
+      if (payload.all === true) {
+        summary.all = true;
+        summary.jid = payload.jid ?? null;
+      } else if (Array.isArray(payload.keys)) {
+        summary.keysCount = payload.keys.length;
+      }
+      break;
+    case 'messages.update':
+      if (Array.isArray(payload)) {
+        summary.updatesCount = payload.length;
+        const firstUpdate = payload[0];
+        const status = normalizeMessageStatus(firstUpdate?.update?.status);
+        const stubType = normalizeMessageStubType(firstUpdate?.update?.messageStubType ?? firstUpdate?.update?.stubType);
+        const addressingMode = resolveAddressingModeFromMessageKey(firstUpdate?.key);
+        summary.pollUpdatesCount = payload.filter((entry) => Array.isArray(entry?.update?.pollUpdates) && entry.update.pollUpdates.length > 0).length;
+        summary.firstStatusCode = status?.code ?? null;
+        summary.firstStatusName = status?.name ?? null;
+        summary.firstStubTypeCode = stubType?.code ?? null;
+        summary.firstStubTypeName = stubType?.name ?? null;
+        summary.firstAddressingMode = addressingMode ?? null;
+      }
+      break;
+    case 'messages.media-update':
+      if (Array.isArray(payload)) {
+        summary.updatesCount = payload.length;
+        summary.withMediaCount = payload.filter((entry) => Boolean(entry?.media)).length;
+        summary.withErrorCount = payload.filter((entry) => Boolean(entry?.error)).length;
+      }
+      break;
+    case 'message-receipt.update':
+      if (Array.isArray(payload)) {
+        summary.receiptsCount = payload.length;
+        const receiptTypes = new Set();
+        for (const entry of payload) {
+          const type = normalizeMessageReceiptType(entry?.receipt?.type);
+          if (type) receiptTypes.add(type);
+        }
+        summary.receiptTypes = Array.from(receiptTypes).slice(0, 8);
+      }
+      break;
+    case 'blocklist.set':
+      summary.blocklistCount = Array.isArray(payload.blocklist) ? payload.blocklist.length : 0;
+      break;
+    case 'blocklist.update':
+      summary.blocklistCount = Array.isArray(payload.blocklist) ? payload.blocklist.length : 0;
+      summary.type = payload.type ?? null;
+      break;
+    case 'group.join-request':
+      summary.groupId = payload.id ?? null;
+      summary.participant = payload.participant ?? null;
+      summary.action = payload.action ?? null;
+      summary.method = payload.method ?? null;
+      break;
+    case 'group.member-tag.update':
+      summary.groupId = payload.groupId ?? null;
+      summary.participant = payload.participant ?? null;
+      summary.label = payload.label ?? null;
+      break;
+    case 'labels.association':
+      summary.type = payload.type ?? null;
+      summary.labelId = payload.association?.labelId ?? null;
+      summary.chatId = payload.association?.chatId ?? null;
+      break;
+    case 'labels.edit':
+      summary.labelId = payload.id ?? null;
+      summary.labelName = payload.name ?? payload.label ?? null;
+      break;
+    case 'newsletter.reaction':
+      summary.id = payload.id ?? null;
+      summary.serverId = payload.server_id ?? null;
+      summary.reactionCode = payload.reaction?.code ?? null;
+      summary.reactionCount = payload.reaction?.count ?? null;
+      summary.reactionRemoved = payload.reaction?.removed ?? null;
+      break;
+    case 'newsletter.view':
+      summary.id = payload.id ?? null;
+      summary.serverId = payload.server_id ?? null;
+      summary.count = payload.count ?? null;
+      break;
+    case 'newsletter-participants.update':
+      summary.id = payload.id ?? null;
+      summary.user = payload.user ?? null;
+      summary.action = payload.action ?? null;
+      summary.newRole = payload.new_role ?? null;
+      break;
+    case 'newsletter-settings.update':
+      summary.id = payload.id ?? null;
+      summary.updateKeys = payload.update ? Object.keys(payload.update).slice(0, 6) : [];
+      break;
+    case 'lid-mapping.update':
+      summary.lid = payload.lid ?? null;
+      summary.pn = payload.pn ?? payload.jid ?? null;
+      break;
+    default:
+      break;
+  }
+
+  return summary;
+};
+
+/**
+ * Determina se um evento específico do Baileys deve ser logado.
+ * @param {string} eventName - O nome do evento do Baileys.
+ * @returns {boolean} True se o evento deve ser logado, false caso contrário.
+ */
+const shouldLogBaileysEvent = (eventName) => {
+  if (!BAILEYS_EVENT_LOG_ENABLED) return false;
+  if (IS_PRODUCTION && BAILEYS_NOISY_EVENTS_IN_PRODUCTION.has(eventName)) return false;
+  return true;
+};
+
+/**
+ * Registra os loggers para os eventos do Baileys.
+ * @param {import('@whiskeysockets/baileys').WASocket} sock - A instância do socket do Baileys.
+ * @returns {void}
+ */
+const registerBaileysEventLoggers = (sock) => {
+  const eventsToLog = BAILEYS_EVENT_NAMES.filter((eventName) => !BAILEYS_EVENTS_WITH_INTERNAL_LOG.has(eventName) && shouldLogBaileysEvent(eventName));
+
+  for (const eventName of eventsToLog) {
+    sock.ev.on(eventName, (payload) => {
+      const summary = summarizeBaileysEventPayload(eventName, payload);
+      logger.debug('Evento Baileys recebido.', {
+        action: 'baileys_event',
+        event: eventName,
+        ...summary,
+        timestamp: new Date().toISOString(),
+      });
+    });
+  }
+
+  logger.debug('Loggers de eventos Baileys registrados.', {
+    action: 'baileys_event_logger_ready',
+    enabled: BAILEYS_EVENT_LOG_ENABLED,
+    eventsCount: eventsToLog.length,
+    events: eventsToLog,
+  });
+};
+
+/**
+ * Determina se um evento do Baileys deve ser persistido no diário de eventos.
+ * @param {string} eventName - O nome do evento do Baileys.
+ * @returns {boolean} True se o evento deve ser persistido, false caso contrário.
+ */
+const shouldPersistBaileysEvent = (eventName) => {
+  if (!BAILEYS_EVENT_JOURNAL_ENABLED) return false;
+  if (BAILEYS_EVENT_JOURNAL_ALL_EVENTS) return BAILEYS_EVENT_NAMES.includes(eventName);
+  return BAILEYS_EVENT_JOURNAL_EVENTS.has(eventName);
+};
+
+/**
+ * Retorna a primeira string não vazia de uma lista de valores.
+ * @param {...(string | null | undefined)} values - Os valores a serem verificados.
+ * @returns {string | null} A primeira string não vazia encontrada ou null.
+ */
+const takeFirstString = (...values) => {
+  for (const value of values) {
+    if (typeof value !== 'string') continue;
+    const normalized = value.trim();
+    if (normalized) return normalized;
+  }
+  return null;
+};
+
+/**
+ * Extrai referências (chatId, messageId, participantId) de um payload de evento do Baileys.
+ * @param {any} payload - O payload do evento do Baileys.
+ * @returns {{chatId: string | null, messageId: string | null, participantId: string | null}} Objeto contendo as referências extraídas.
+ */
+const extractBaileysEventReferences = (payload) => {
+  const refs = {
+    chatId: null,
+    messageId: null,
+    participantId: null,
+  };
+
+  const assignChat = (...values) => {
+    if (refs.chatId) return;
+    refs.chatId = takeFirstString(...values);
+  };
+
+  const assignMessage = (...values) => {
+    if (refs.messageId) return;
+    refs.messageId = takeFirstString(...values);
+  };
+
+  const assignParticipant = (...values) => {
+    if (refs.participantId) return;
+    refs.participantId = takeFirstString(...values);
+  };
+
+  const applyFromKey = (key) => {
+    if (!key || typeof key !== 'object') return;
+    assignChat(key.remoteJid, key.remoteJidAlt);
+    assignMessage(key.id);
+    assignParticipant(key.participant, key.participantAlt);
+  };
+
+  const applyFromObject = (value) => {
+    if (!value || typeof value !== 'object') return;
+
+    applyFromKey(value.key);
+    applyFromKey(value.msg?.key);
+    applyFromKey(value.reaction?.key);
+    applyFromKey(value.reactionMessage?.key);
+    applyFromKey(value.reactedKey);
+
+    assignChat(value.id, value.groupId, value.jid, value.chatId);
+    assignMessage(value.messageId, value.msgId, value.server_id);
+    assignParticipant(value.participant, value.user, value.lid, value.pn);
+
+    if (Array.isArray(value.participants) && value.participants.length > 0) {
+      assignParticipant(value.participants[0]);
+    }
+    if (Array.isArray(value.keys) && value.keys.length > 0) {
+      applyFromKey(value.keys[0]);
+    }
+    if (Array.isArray(value.messages) && value.messages.length > 0) {
+      applyFromObject(value.messages[0]);
+    }
+  };
+
+  if (Array.isArray(payload)) {
+    for (const item of payload) {
+      applyFromObject(item);
+      if (refs.chatId && refs.messageId && refs.participantId) break;
+    }
+  } else {
+    applyFromObject(payload);
+  }
+
+  return refs;
+};
+
+/**
+ * Resolve IDs de contato (LID/JID) a partir de payloads de contacts.upsert/contacts.update.
+ * @param {any} contact
+ * @returns {{lid: string | null, jid: string | null}}
+ */
+const resolveContactIdsForLidMap = (contact) => {
+  const lidCandidates = [contact?.lid, contact?.id, contact?.jid];
+  let lid = null;
+  for (const candidate of lidCandidates) {
+    if (isLidUserId(candidate)) {
+      lid = candidate;
+      break;
+    }
+  }
+
+  const jidCandidates = [contact?.jid, contact?.phoneNumber, contact?.id];
+  let jid = null;
+  for (const candidate of jidCandidates) {
+    if (isWhatsAppUserId(candidate)) {
+      jid = candidate;
+      break;
+    }
+    const normalizedPn = normalizePnToJid(candidate);
+    if (normalizedPn && isWhatsAppUserId(normalizedPn)) {
+      jid = normalizedPn;
+      break;
+    }
+  }
+
+  return { lid, jid };
+};
+
+/**
+ * Enfileira atualizações do lid_map a partir de eventos de contato.
+ * @param {Array<any>} contacts
+ * @param {string} source
+ * @returns {void}
+ */
+const queueContactsLidUpdates = (contacts, source) => {
+  if (!Array.isArray(contacts) || contacts.length === 0) return;
+
+  for (const contact of contacts) {
+    try {
+      const { lid, jid } = resolveContactIdsForLidMap(contact);
+      if (!lid) continue;
+      queueLidUpdate(lid, jid, source);
+    } catch (error) {
+      logger.warn('Falha ao processar evento de contatos para lid_map.', {
+        source,
+        error: error.message,
+      });
+    }
+  }
+};
+
+/**
+ * Registra o mecanismo de diário (journal) para os eventos do Baileys.
+ * Eventos selecionados são enfileirados para persistência.
+ * @param {import('@whiskeysockets/baileys').WASocket} sock - A instância do socket do Baileys.
+ * @param {number} generation - A geração atual do socket.
+ * @returns {void}
+ */
+const registerBaileysEventJournal = (sock, generation) => {
+  if (!BAILEYS_EVENT_JOURNAL_ENABLED) {
+    logger.debug('Journal de eventos Baileys desativado por configuração.', {
+      action: 'baileys_event_journal_disabled',
+    });
+    return;
+  }
+
+  const unknownEvents = BAILEYS_EVENT_JOURNAL_EVENT_LIST.filter((eventName) => eventName !== '*' && !BAILEYS_EVENT_NAMES.includes(eventName));
+  if (unknownEvents.length > 0) {
+    logger.warn('Alguns eventos configurados para journal não existem na lista conhecida do Baileys.', {
+      action: 'baileys_event_journal_unknown_events',
+      unknownEvents,
+    });
+  }
+
+  const eventsToPersist = BAILEYS_EVENT_NAMES.filter((eventName) => shouldPersistBaileysEvent(eventName));
+  if (eventsToPersist.length === 0) {
+    logger.warn('Journal de eventos Baileys habilitado sem eventos válidos para persistir.', {
+      action: 'baileys_event_journal_empty',
+      configuredEvents: BAILEYS_EVENT_JOURNAL_EVENT_LIST,
+    });
+    return;
+  }
+
+  for (const eventName of eventsToPersist) {
+    sock.ev.on(eventName, (payload) => {
+      try {
+        const summary = summarizeBaileysEventPayload(eventName, payload);
+        const refs = extractBaileysEventReferences(payload);
+        queueBaileysEventInsert({
+          event_name: eventName,
+          socket_generation: generation,
+          chat_id: refs.chatId,
+          message_id: refs.messageId,
+          participant_id: refs.participantId,
+          payload_summary: summary,
+          event_timestamp: new Date(),
+        });
+      } catch (error) {
+        logger.warn('Falha ao enfileirar evento Baileys para journal.', {
+          action: 'baileys_event_journal_enqueue_failed',
+          eventName,
+          error: error?.message,
+        });
+      }
+    });
+  }
+
+  logger.info('Journal de eventos Baileys habilitado.', {
+    action: 'baileys_event_journal_ready',
+    generation,
+    eventsCount: eventsToPersist.length,
+    events: eventsToPersist,
+  });
+};
+
+/**
+ * Faz parse seguro de JSON com suporte a Buffer e retorna fallback em caso de erro.
+ * @param {unknown} value - Valor a ser interpretado.
+ * @param {any} fallback - Valor retornado quando o parse falha ou o valor é inválido.
+ * @returns {any} Objeto parseado ou fallback.
+ */
+const safeJsonParse = (value, fallback) => {
+  if (value === null || value === undefined) return fallback;
+  if (Buffer.isBuffer(value)) {
+    return safeJsonParse(value.toString('utf8'), fallback);
+  }
+  if (typeof value === 'object') return value;
+  if (typeof value !== 'string') return fallback;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    logger.warn('Falha ao fazer parse de JSON armazenado.', {
+      error: error.message,
+    });
+    return fallback;
+  }
+};
+
+/**
+ * Normaliza PN para JID de WhatsApp quando o payload vier sem domínio.
+ * @param {string|null|undefined} pn
+ * @returns {string|null}
+ */
+/**
+ * Persiste mensagens recebidas quando o tipo do upsert permite salvamento.
+ * @async
+ * @param {Array<import('@whiskeysockets/baileys').WAMessage>} incomingMessages - Mensagens recebidas.
+ * @param {'append' | 'notify' | string} type - Tipo do evento de upsert.
+ * @returns {Promise<void>} Conclusão da persistência.
+ */
+async function persistIncomingMessages(incomingMessages, type) {
+  if (type !== 'append' && type !== 'notify') return;
+
+  const entries = [];
+  const lidsToPrime = new Set();
+
+  for (const msg of incomingMessages) {
+    if (!msg.message || msg.key.remoteJid === 'status@broadcast') continue;
+    const resolvedAddressingMode = resolveAddressingModeFromMessageKey(msg?.key);
+    const normalizedMsg =
+      resolvedAddressingMode && msg?.key && msg.key.addressingMode !== resolvedAddressingMode
+        ? {
+            ...msg,
+            key: {
+              ...msg.key,
+              addressingMode: resolvedAddressingMode,
+            },
+          }
+        : msg;
+
+    const senderInfo = extractSenderInfoFromMessage(normalizedMsg);
+    if (senderInfo.lid) lidsToPrime.add(senderInfo.lid);
+    entries.push({ msg: normalizedMsg, senderInfo });
+  }
+
+  if (lidsToPrime.size > 0) {
+    try {
+      await primeLidCache(Array.from(lidsToPrime));
+    } catch (error) {
+      logger.warn('Falha ao aquecer cache de LID.', { error: error.message });
+    }
+  }
+
+  for (const { msg, senderInfo } of entries) {
+    if (senderInfo.lid) {
+      queueLidUpdate(senderInfo.lid, senderInfo.jid, 'message');
+    }
+
+    const canonicalSenderId = resolveUserIdCached(senderInfo) || msg.key.participant || msg.key.remoteJid;
+
+    const messageData = buildMessageData(msg, canonicalSenderId);
+    queueMessageInsert(messageData);
+  }
+}
+
+/**
+ * Recupera mensagem armazenada para suporte a recursos (ex.: enquetes) do Baileys.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAMessageKey} key - Chave da mensagem.
+ * @returns {Promise<import('@whiskeysockets/baileys').proto.IMessage | undefined>} Conteúdo da mensagem armazenada.
+ */
+async function getStoredMessage(key) {
+  const messageId = key?.id;
+  const remoteJid = key?.remoteJid;
+  if (!messageId || !remoteJid) return undefined;
+
+  try {
+    const results = await findBy('messages', { message_id: messageId, chat_id: remoteJid }, { limit: 1 });
+    const record = results?.[0];
+    const stored = safeJsonParse(record?.raw_message, null);
+    if (record?.raw_message && !stored) {
+      logger.error('Falha ao interpretar raw_message armazenado.', {
+        messageId,
+        remoteJid,
+      });
+    }
+    return stored?.message ?? undefined;
+  } catch (error) {
+    logger.error('Erro ao buscar mensagem armazenada no banco:', {
+      error: error.message,
+      messageId,
+      remoteJid,
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Limpa o timeout de reconexão agendado, se houver.
+ * @returns {void}
+ */
+const clearReconnectTimeout = () => {
+  if (!reconnectTimeout) return;
+  reconnectTimeout.cancel();
+  reconnectTimeout = null;
+};
+
+/**
+ * Reseta o estado das tentativas de reconexão.
+ * @returns {void}
+ */
+const resetReconnectState = () => {
+  connectionAttempts = 0;
+  reconnectWindowStartedAt = 0;
+};
+
+/**
+ * Calcula o número da próxima tentativa de reconexão.
+ * Reseta a contagem de tentativas se a janela de reconexão expirou.
+ * @returns {number} O número da próxima tentativa.
+ */
+const getNextReconnectAttempt = () => {
+  const now = Date.now();
+  if (!reconnectWindowStartedAt || now - reconnectWindowStartedAt >= BAILEYS_RECONNECT_ATTEMPT_RESET_MS) {
+    reconnectWindowStartedAt = now;
+    connectionAttempts = 0;
+  }
+  connectionAttempts += 1;
+  return connectionAttempts;
+};
+
+/**
+ * Agenda uma reconexão com o WhatsApp após um determinado atraso.
+ * Evita agendar múltiplas reconexões.
+ * @param {number} delay - O atraso em milissegundos antes de tentar a reconexão.
+ * @returns {void}
+ */
+const scheduleReconnect = (delay) => {
+  if (reconnectTimeout) return;
+  const pendingReconnect = delayCancellable(Math.max(0, Number(delay) || 0));
+  reconnectTimeout = pendingReconnect;
+  pendingReconnect.delay
+    .then(() => {
+      if (reconnectTimeout !== pendingReconnect) return;
+      reconnectTimeout = null;
+      connectToWhatsApp().catch((error) => {
+        logger.error('Falha ao executar reconexão agendada.', {
+          action: 'reconnect_schedule_failure',
+          errorMessage: error?.message,
+          stack: error?.stack,
+          timestamp: new Date().toISOString(),
+        });
+      });
+    })
+    .catch((error) => {
+      if (reconnectTimeout === pendingReconnect) {
+        reconnectTimeout = null;
+      }
+      if (
+        String(error?.message || '')
+          .trim()
+          .toLowerCase() === 'cancelled'
+      ) {
+        return;
+      }
+      logger.warn('Falha ao aguardar atraso da reconexão agendada.', {
+        action: 'reconnect_schedule_delay_error',
+        errorMessage: error?.message,
+      });
+    });
+};
+
+/**
+ * Libera lock de escritor único do Baileys, se estiver ativo.
+ * @param {string} reason
+ * @returns {Promise<void>}
+ */
+const releaseBaileysWriterLock = async (reason = 'unknown') => {
+  const connection = baileysWriterLockConnection;
+  if (!connection) return;
+
+  baileysWriterLockConnection = null;
+
+  try {
+    const rows = await executeQuery('SELECT RELEASE_LOCK(?) AS released', [BAILEYS_SINGLE_WRITER_LOCK_NAME], connection);
+    const released = Number(rows?.[0]?.released) === 1;
+    logger.info('Lock de escritor do Baileys liberado.', {
+      action: 'baileys_writer_lock_released',
+      reason,
+      released,
+      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (error) {
+    logger.warn('Falha ao liberar lock de escritor do Baileys.', {
+      action: 'baileys_writer_lock_release_error',
+      reason,
+      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      errorMessage: error?.message,
+      timestamp: new Date().toISOString(),
+    });
+  } finally {
+    try {
+      connection.release();
+    } catch (error) {
+      logger.debug('Conexao dedicada do lock ja estava encerrada.', {
+        action: 'baileys_writer_lock_connection_already_closed',
+        errorMessage: error?.message,
+      });
+    }
+  }
+};
+
+/**
+ * Garante lock de escritor único para a sessão do Baileys.
+ * @returns {Promise<boolean>}
+ */
+const ensureBaileysWriterLock = async () => {
+  if (!BAILEYS_SINGLE_WRITER_LOCK_ENABLED) {
+    return true;
+  }
+
+  if (baileysWriterLockConnection) {
+    return true;
+  }
+
+  const connection = await pool.getConnection();
+
+  try {
+    const rows = await executeQuery('SELECT GET_LOCK(?, ?) AS lock_status', [BAILEYS_SINGLE_WRITER_LOCK_NAME, BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS], connection);
+    const lockStatus = Number(rows?.[0]?.lock_status);
+    if (lockStatus !== 1) {
+      connection.release();
+      logger.warn('Nao foi possivel adquirir lock de escritor do Baileys nesta tentativa.', {
+        action: 'baileys_writer_lock_busy',
+        lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+        timeoutSeconds: BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS,
+        status: Number.isFinite(lockStatus) ? lockStatus : null,
+        retryAfterMs: BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS,
+        timestamp: new Date().toISOString(),
+      });
+      return false;
+    }
+
+    baileysWriterLockConnection = connection;
+    logger.info('Lock de escritor do Baileys adquirido com sucesso.', {
+      action: 'baileys_writer_lock_acquired',
+      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      timeoutSeconds: BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS,
+      timestamp: new Date().toISOString(),
+    });
+    return true;
+  } catch (error) {
+    try {
+      connection.release();
+    } catch {
+      // Ignora falhas ao liberar conexão após erro de aquisição.
+    }
+    throw error;
+  }
+};
+
+process.once('beforeExit', () => {
+  releaseBaileysWriterLock('before_exit').catch(() => {});
+});
+
+process.once('SIGINT', () => {
+  releaseBaileysWriterLock('sigint').catch(() => {});
+});
+
+process.once('SIGTERM', () => {
+  releaseBaileysWriterLock('sigterm').catch(() => {});
+});
+
+/**
+ * Envolve uma promessa com um timeout. Se a promessa não resolver dentro do tempo limite, ela é rejeitada.
+ * @template T
+ * @param {Promise<T>} promise - A promessa a ser envolvida.
+ * @param {number} timeoutMs - O tempo limite em milissegundos.
+ * @param {string} [timeoutLabel='operation_timeout'] - Rótulo para o erro de timeout.
+ * @returns {Promise<T>} A promessa envolvida com timeout.
+ */
+const withTimeout = (promise, timeoutMs, timeoutLabel = 'operation_timeout') =>
+  promiseTimeout(timeoutMs, (resolve, reject) => {
+    promise.then(resolve).catch(reject);
+  }).catch((error) => {
+    if (
+      String(error?.message || '')
+        .trim()
+        .toLowerCase() === 'timed out'
+    ) {
+      throw new Error(timeoutLabel);
+    }
+    throw error;
+  });
+
+/**
+ * Sincroniza metadados de grupos ao abrir a conexão com o WhatsApp.
+ * Busca todos os grupos participantes e os atualiza no banco de dados.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WASocket} sock - A instância do socket do Baileys.
+ * @returns {Promise<void>}
+ */
+const syncGroupsOnConnectionOpen = async (sock) => {
+  if (!GROUP_SYNC_ON_CONNECT) {
+    logger.info('Sincronização de grupos no connect desativada por configuração.', {
+      action: 'groups_sync_disabled',
+      timestamp: new Date().toISOString(),
+    });
+    return;
+  }
+
+  const allGroups = await withTimeout(sock.groupFetchAllParticipating(), GROUP_SYNC_TIMEOUT_MS, `groups_sync_timeout_${GROUP_SYNC_TIMEOUT_MS}ms`);
+  const allGroupEntries = Object.values(allGroups || {});
+  const selectedGroups = GROUP_SYNC_MAX_GROUPS > 0 ? allGroupEntries.slice(0, GROUP_SYNC_MAX_GROUPS) : allGroupEntries;
+
+  let syncedCount = 0;
+  let failedCount = 0;
+
+  for (let offset = 0; offset < selectedGroups.length; offset += GROUP_SYNC_BATCH_SIZE) {
+    const batch = selectedGroups.slice(offset, offset + GROUP_SYNC_BATCH_SIZE);
+    const results = await Promise.allSettled(
+      batch.map((group) =>
+        upsertGroupMetadata(group.id, buildGroupMetadataFromGroup(group), {
+          mergeExisting: false,
+        }).then((result) => {
+          invalidateCachedGroupMetadata(group.id);
+          return result;
+        }),
+      ),
+    );
+    for (const result of results) {
+      if (result.status === 'fulfilled') syncedCount += 1;
+      else failedCount += 1;
+    }
+  }
+
+  logger.info('📁 Metadados de grupos sincronizados com MySQL.', {
+    action: 'groups_synced',
+    totalFetched: allGroupEntries.length,
+    totalSynced: syncedCount,
+    totalFailed: failedCount,
+    totalSkipped: Math.max(0, allGroupEntries.length - selectedGroups.length),
+    batchSize: GROUP_SYNC_BATCH_SIZE,
+    maxGroups: GROUP_SYNC_MAX_GROUPS > 0 ? GROUP_SYNC_MAX_GROUPS : null,
+    timeoutMs: GROUP_SYNC_TIMEOUT_MS,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Inicia e gerencia a conexão com o WhatsApp usando o Baileys.
+ * Configura autenticação, cria o socket e registra handlers de eventos.
+ * Gerencia a lógica de reconexão e a distribuição de eventos.
+ * @async
+ * @returns {Promise<void>} Conclusão da inicialização e do registro de handlers.
+ * @throws {Error} Lança erro se a conexão inicial falhar.
+ */
+export async function connectToWhatsApp() {
+  if (connectPromise) {
+    return connectPromise;
+  }
+
+  if (isSocketOpen(activeSocket)) {
+    return;
+  }
+
+  logger.info('Iniciando conexão com o WhatsApp...', {
+    action: 'connect_init',
+    timestamp: new Date().toISOString(),
+  });
+  connectPromise = (async () => {
+    clearReconnectTimeout();
+    const isWriterReady = await ensureBaileysWriterLock();
+    if (!isWriterReady) {
+      scheduleReconnect(BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS);
+      return;
+    }
+
+    const generation = ++socketGeneration;
+    const legacyAuthPath = path.join(__dirname, 'auth');
+    const { state, saveCreds } = await useDbAuthState({
+      sessionId: BAILEYS_AUTH_SESSION_ID,
+      bootstrapFromDir: legacyAuthPath,
+      bootstrapFromFiles: BAILEYS_AUTH_BOOTSTRAP_FROM_FILES,
+    });
+
+    const version = await resolveBaileysVersion();
+
+    logger.debug('Dados de autenticação carregados com sucesso.', {
+      authSessionId: BAILEYS_AUTH_SESSION_ID,
+      bootstrappedFromFiles: BAILEYS_AUTH_BOOTSTRAP_FROM_FILES,
+      version,
+      generation,
+    });
+
+    /** @type {import('@whiskeysockets/baileys').UserFacingSocketConfig} */
+    const socketConfig = {
+      version,
+      auth: state,
+      logger: baileysSocketLogger,
+      browser: Browsers.macOS('Desktop'),
+      qrTimeout: 30000,
+      syncFullHistory: false,
+      markOnlineOnConnect: true,
+      msgRetryCounterCache,
+      maxMsgRetryCount: 5,
+      retryRequestDelayMs: 250,
+      getMessage: getStoredMessage,
+      userDevicesCache,
+      mediaCache,
+      cachedGroupMetadata: resolveCachedGroupMetadata,
+      patchMessageBeforeSending,
+      enableAutoSessionRecreation: BAILEYS_ENABLE_AUTO_SESSION_RECREATION,
+      enableRecentMessageCache: BAILEYS_ENABLE_RECENT_MESSAGE_CACHE,
+      generateHighQualityLinkPreview: BAILEYS_GENERATE_HIGH_QUALITY_LINK_PREVIEW,
+    };
+
+    const sock = makeWASocket(socketConfig);
+
+    activeSocket = sock;
+    storeActiveSocket(sock);
+
+    const isCurrentSocket = () => activeSocket === sock && generation === socketGeneration;
+
+    sock.ev.on('creds.update', async () => {
+      if (!isCurrentSocket()) return;
+      logger.debug('Atualizando credenciais de autenticação...', {
+        action: 'creds_update',
+        timestamp: new Date().toISOString(),
+      });
+      await saveCreds();
+    });
+
+    sock.ev.on('connection.update', (update) => {
+      if (!isCurrentSocket()) return;
+      handleConnectionUpdate(update, sock);
+      if (update.connection === 'open') {
+        syncNewsBroadcastService();
+      }
+      logger.debug('Estado da conexão atualizado.', {
+        action: 'connection_update',
+        status: update.connection,
+        lastDisconnect: update.lastDisconnect?.error?.message || null,
+        isNewLogin: update.isNewLogin || false,
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    sock.ev.on('messages.upsert', (update) => {
+      if (!isCurrentSocket()) return;
+      const start = process.hrtime.bigint();
+      const messagesCount = Array.isArray(update?.messages) ? update.messages.length : 0;
+      const eventType = update?.type || 'unknown';
+      try {
+        logger.debug('Novo(s) evento(s) em messages.upsert', {
+          action: 'messages_upsert',
+          type: update.type,
+          messagesCount: update.messages.length,
+          remoteJid: update.messages[0]?.key.remoteJid || null,
+        });
+        const persistPromise = persistIncomingMessages(update.messages, update.type).catch((error) => {
+          logger.error('Erro ao persistir mensagens no banco de dados:', {
+            error: error.message,
+          });
+          recordError('messages_upsert');
+        });
+        const handlePromise = handleMessages(update, sock).catch((error) => {
+          recordError('messages_upsert');
+          throw error;
+        });
+
+        Promise.allSettled([persistPromise, handlePromise]).then((results) => {
+          const ok = results.every((result) => result.status === 'fulfilled');
+          const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+          recordMessagesUpsert({
+            durationMs,
+            type: eventType,
+            messagesCount,
+            ok,
+          });
+        });
+      } catch (error) {
+        logger.error('Erro no evento messages.upsert:', {
+          error: error.message,
+          stack: error.stack,
+          action: 'messages_upsert_error',
+        });
+        recordError('messages_upsert');
+        const durationMs = Number(process.hrtime.bigint() - start) / 1e6;
+        recordMessagesUpsert({
+          durationMs,
+          type: eventType,
+          messagesCount,
+          ok: false,
+        });
+      }
+    });
+
+    sock.ev.on('chats.upsert', (newChats) => {
+      if (!isCurrentSocket()) return;
+      for (const chat of newChats) {
+        queueChatUpdate(chat, { partial: false, forceName: true });
+      }
+    });
+
+    sock.ev.on('chats.update', (updates) => {
+      if (!isCurrentSocket()) return;
+      for (const update of updates) {
+        queueChatUpdate(update, { partial: true });
+      }
+    });
+
+    sock.ev.on('chats.delete', (deletions) => {
+      if (!isCurrentSocket()) return;
+      for (const chatId of deletions) {
+        remove('chats', chatId).catch((error) => {
+          logger.error('Erro ao remover chat do banco:', {
+            error: error.message,
+            chatId,
+          });
+        });
+      }
+    });
+
+    sock.ev.on('groups.upsert', async (newGroups) => {
+      if (!isCurrentSocket()) return;
+      for (const group of newGroups) {
+        try {
+          await upsertGroupMetadata(group.id, buildGroupMetadataFromGroup(group), {
+            mergeExisting: false,
+          });
+          invalidateCachedGroupMetadata(group.id);
+        } catch (error) {
+          logger.error('Erro no upsert do grupo:', {
+            error: error.message,
+            groupId: group.id,
+          });
+        }
+      }
+    });
+
+    sock.ev.on('contacts.upsert', (contacts) => {
+      if (!isCurrentSocket()) return;
+      queueContactsLidUpdates(contacts, 'contacts.upsert');
+    });
+
+    sock.ev.on('contacts.update', (updates) => {
+      if (!isCurrentSocket()) return;
+      queueContactsLidUpdates(updates, 'contacts.update');
+    });
+
+    sock.ev.on('lid-mapping.update', (update) => {
+      if (!isCurrentSocket()) return;
+      try {
+        const lid = typeof update?.lid === 'string' ? update.lid : null;
+        const pnJid = normalizePnToJid(update?.pn);
+        if (!lid || !pnJid) return;
+        queueLidUpdate(lid, pnJid, 'lid-mapping');
+      } catch (error) {
+        logger.warn('Falha ao processar lid-mapping.update para lid_map.', {
+          error: error.message,
+        });
+      }
+    });
+
+    sock.ev.on('messages.update', (update) => {
+      if (!isCurrentSocket()) return;
+      try {
+        logger.debug('Atualização de mensagens recebida.', {
+          action: 'messages_update',
+          updatesCount: update.length,
+        });
+        handleMessageUpdate(update, sock);
+      } catch (error) {
+        logger.error('Erro no evento messages.update:', {
+          error: error.message,
+          stack: error.stack,
+          action: 'messages_update_error',
+        });
+      }
+    });
+
+    sock.ev.on('messages.media-update', (updates) => {
+      if (!isCurrentSocket()) return;
+      if (!Array.isArray(updates)) return;
+
+      const erroredUpdates = updates.filter((entry) => entry?.error);
+      if (erroredUpdates.length > 0) {
+        const firstError = erroredUpdates[0]?.error;
+        logger.warn('Falha reportada em atualização de mídia.', {
+          action: 'messages_media_update_error',
+          updatesCount: updates.length,
+          errorCount: erroredUpdates.length,
+          firstMessageId: erroredUpdates[0]?.key?.id || null,
+          firstRemoteJid: erroredUpdates[0]?.key?.remoteJid || null,
+          firstErrorMessage: firstError?.message || null,
+        });
+        return;
+      }
+
+      logger.debug('Atualização de mídia de mensagem recebida.', {
+        action: 'messages_media_update',
+        updatesCount: updates.length,
+      });
+    });
+
+    sock.ev.on('message-receipt.update', (updates) => {
+      if (!isCurrentSocket()) return;
+      if (!Array.isArray(updates) || updates.length === 0) return;
+
+      const receiptTypes = new Set();
+      let invalidReceiptTypeCount = 0;
+      for (const update of updates) {
+        const receiptType = normalizeMessageReceiptType(update?.receipt?.type);
+        if (receiptType) {
+          receiptTypes.add(receiptType);
+        } else if (update?.receipt?.type !== undefined) {
+          invalidReceiptTypeCount += 1;
+        }
+      }
+
+      logger.debug('Atualização de recibos de mensagem recebida.', {
+        action: 'message_receipt_update',
+        updatesCount: updates.length,
+        receiptTypes: Array.from(receiptTypes),
+        invalidReceiptTypeCount,
+        sampleMessageId: updates[0]?.key?.id || null,
+        sampleRemoteJid: updates[0]?.key?.remoteJid || null,
+      });
+    });
+
+    sock.ev.on('messages.reaction', async (updates) => {
+      if (!isCurrentSocket()) return;
+      try {
+        const reactions = Array.isArray(updates) ? updates : [updates];
+        for (const update of reactions) {
+          const key = update?.key || update?.msg?.key || update?.reaction?.key || null;
+          const reaction = update?.reaction || update?.msg?.reaction || update?.reactionMessage || null;
+          const reactedKey = reaction?.key || update?.reactedKey || update?.reactionMessage?.key || null;
+
+          const groupId = key?.remoteJid || reactedKey?.remoteJid || null;
+          const senderJid = key?.participant || update?.participant || reaction?.sender || null;
+          const senderIdentity = {
+            participant: key?.participant || update?.participant || reaction?.sender || null,
+            participantAlt: key?.participantAlt || update?.participantAlt || reaction?.participantAlt || reaction?.key?.participantAlt || null,
+            jid: senderJid,
+          };
+          const reactedMessageId = reactedKey?.id || null;
+          const reactionText = typeof reaction?.text === 'string' ? reaction.text : '';
+
+          if (groupId && (senderJid || senderIdentity.participantAlt)) {
+            await resolveCaptchaByReaction({
+              groupId,
+              senderJid,
+              senderIdentity,
+              reactedMessageId,
+              reactionText,
+            });
+          }
+        }
+      } catch (error) {
+        logger.error('Erro no evento messages.reaction:', {
+          error: error.message,
+          stack: error.stack,
+          action: 'messages_reaction_error',
+        });
+      }
+    });
+
+    sock.ev.on('groups.update', (updates) => {
+      if (!isCurrentSocket()) return;
+      try {
+        logger.debug('Grupo(s) atualizado(s).', {
+          action: 'groups_update',
+          groupCount: updates.length,
+          groupIds: updates.map((u) => u.id),
+        });
+        handleGroupUpdate(updates);
+      } catch (err) {
+        logger.error('Erro no evento groups.update:', {
+          error: err.message,
+          stack: err.stack,
+          action: 'groups_update_error',
+        });
+      }
+    });
+
+    sock.ev.on('group-participants.update', (update) => {
+      if (!isCurrentSocket()) return;
+      try {
+        logger.debug('Participantes do grupo atualizados.', {
+          action: 'group_participants_update',
+          groupId: update.id,
+          actionType: update.action,
+          participants: update.participants,
+        });
+        invalidateCachedGroupMetadata(update.id);
+        handleGroupParticipantsEvent(sock, update.id, update.participants, update.action);
+      } catch (err) {
+        logger.error('Erro no evento group-participants.update:', {
+          error: err.message,
+          stack: err.stack,
+          action: 'group_participants_update_error',
+        });
+      }
+    });
+
+    sock.ev.on('group.join-request', (update) => {
+      if (!isCurrentSocket()) return;
+      try {
+        logger.debug('Solicitação de entrada no grupo recebida.', {
+          action: 'group_join_request',
+          groupId: update?.id,
+          participant: update?.participant,
+          method: update?.method,
+          joinAction: update?.action,
+        });
+        handleGroupJoinRequest(sock, update);
+      } catch (err) {
+        logger.error('Erro no evento group.join-request:', {
+          error: err.message,
+          stack: err.stack,
+          action: 'group_join_request_error',
+        });
+      }
+    });
+
+    sock.ev.on('call', async (calls) => {
+      if (!isCurrentSocket()) return;
+      if (!BAILEYS_AUTO_REJECT_CALLS) return;
+      if (!Array.isArray(calls)) return;
+
+      for (const call of calls) {
+        try {
+          if (!call || call.status !== 'offer') continue;
+          if (!call.id || !call.from) continue;
+
+          const myJid = sock.user?.id || null;
+          if (myJid && areJidsSameUser(call.from, myJid)) {
+            continue;
+          }
+
+          await sock.rejectCall(call.id, call.from);
+          logger.info('Chamada recebida rejeitada automaticamente.', {
+            action: 'call_auto_reject',
+            callId: call.id,
+            from: call.from,
+            isGroup: call.isGroup || false,
+            isVideo: call.isVideo || false,
+            timestamp: new Date().toISOString(),
+          });
+        } catch (error) {
+          logger.warn('Falha ao rejeitar chamada automaticamente.', {
+            action: 'call_auto_reject_failed',
+            callId: call?.id || null,
+            from: call?.from || null,
+            error: error?.message,
+          });
+        }
+      }
+    });
+
+    registerBaileysEventLoggers(sock);
+    registerBaileysEventJournal(sock, generation);
+
+    logger.info('Conexão com o WhatsApp estabelecida com sucesso.', {
+      action: 'connect_success',
+      generation,
+      timestamp: new Date().toISOString(),
+    });
+  })();
+
+  try {
+    await connectPromise;
+  } finally {
+    connectPromise = null;
+  }
+}
+
+/**
+ * Gerencia atualizações de estado da conexão com o WhatsApp.
+ * Lida com a exibição de QR code, reconexão automática e ações pós-conexão (como a sincronização de grupos).
+ * @async
+ * @param {import('@whiskeysockets/baileys').ConnectionState} update - Objeto contendo o estado atual da conexão.
+ * @param {import('@whiskeysockets/baileys').WASocket} sock - Instância do socket do WhatsApp que disparou a atualização.
+ * @returns {Promise<void>} Uma promessa que resolve quando o processamento do estado da conexão é concluído.
+ */
+async function handleConnectionUpdate(update, sock) {
+  if (sock !== activeSocket) return;
+  const { connection, lastDisconnect, qr } = update;
+
+  if (qr) {
+    logger.info('📱 QR Code gerado! Escaneie com seu WhatsApp.', {
+      action: 'qr_code_generated',
+      timestamp: new Date().toISOString(),
+    });
+    qrcode.generate(qr, { small: true });
+  }
+
+  if (connection === 'close') {
+    const disconnectCode = lastDisconnect?.error?.output?.statusCode || 'unknown';
+    const errorMessage = lastDisconnect?.error?.message || 'Sem mensagem de erro';
+
+    const shouldReconnect = lastDisconnect?.error instanceof Boom && disconnectCode !== DisconnectReason.loggedOut;
+
+    if (shouldReconnect) {
+      const attempt = getNextReconnectAttempt();
+      if (attempt <= MAX_CONNECTION_ATTEMPTS) {
+        const reconnectDelay = INITIAL_RECONNECT_DELAY * Math.pow(2, attempt - 1);
+        logger.warn(`⚠️ Conexão perdida. Tentando reconectar...`, {
+          action: 'reconnect_attempt',
+          attempt,
+          maxAttempts: MAX_CONNECTION_ATTEMPTS,
+          delay: reconnectDelay,
+          reasonCode: disconnectCode,
+          errorMessage,
+          timestamp: new Date().toISOString(),
+        });
+        activeSocket = null;
+        storeActiveSocket(null);
+        scheduleReconnect(reconnectDelay);
+      } else {
+        logger.error('❌ Limite de tentativas atingido; aguardando janela para novo retry.', {
+          action: 'reconnect_backoff_window',
+          totalAttempts: attempt,
+          maxAttempts: MAX_CONNECTION_ATTEMPTS,
+          retryAfterMs: BAILEYS_RECONNECT_ATTEMPT_RESET_MS,
+          reasonCode: disconnectCode,
+          errorMessage,
+          timestamp: new Date().toISOString(),
+        });
+        activeSocket = null;
+        storeActiveSocket(null);
+        connectionAttempts = 0;
+        reconnectWindowStartedAt = Date.now();
+        scheduleReconnect(BAILEYS_RECONNECT_ATTEMPT_RESET_MS);
+      }
+    } else {
+      logger.error('❌ Conexão fechada definitivamente.', {
+        action: 'connection_closed',
+        reasonCode: disconnectCode,
+        errorMessage,
+        timestamp: new Date().toISOString(),
+      });
+      activeSocket = null;
+      storeActiveSocket(null);
+      await releaseBaileysWriterLock('connection_closed_no_reconnect');
+    }
+  }
+
+  if (connection === 'open') {
+    logger.info('✅ Conectado com sucesso ao WhatsApp!', {
+      action: 'connection_open',
+      timestamp: new Date().toISOString(),
+    });
+
+    resetReconnectState();
+    clearReconnectTimeout();
+
+    if (process.send) {
+      process.send('ready');
+      logger.info('🟢 Sinal de "ready" enviado ao PM2.', {
+        action: 'pm2_ready_signal',
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    try {
+      await syncGroupsOnConnectionOpen(sock);
+    } catch (error) {
+      logger.error('❌ Erro ao carregar metadados de grupos na conexão.', {
+        action: 'groups_load_error',
+        errorMessage: error.message,
+        stack: error.stack,
+        timeoutMs: GROUP_SYNC_TIMEOUT_MS,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+}
+
+/**
+ * Processa atualizações em mensagens existentes, como votos em enquetes.
+ * @async
+ * @param {Array<import('@whiskeysockets/baileys').WAMessageUpdate>} updates - Array de objetos de atualização de mensagens.
+ * @param {import('@whiskeysockets/baileys').WASocket} sock - Instância do socket do WhatsApp.
+ * @returns {Promise<void>} Uma promessa que resolve quando o processamento das atualizações é concluído.
+ */
+async function handleMessageUpdate(updates, sock) {
+  for (const { key, update } of updates) {
+    const status = normalizeMessageStatus(update?.status);
+    const stubType = normalizeMessageStubType(update?.messageStubType ?? update?.stubType);
+    const addressingMode = resolveAddressingModeFromMessageKey(key);
+
+    if (status || stubType || addressingMode) {
+      logger.debug('Atualização de estado da mensagem recebida.', {
+        action: 'message_state_update',
+        remoteJid: key?.remoteJid || null,
+        messageId: key?.id || null,
+        participant: key?.participant || null,
+        participantAlt: key?.participantAlt || null,
+        addressingMode: addressingMode || null,
+        statusCode: status?.code ?? null,
+        statusName: status?.name ?? null,
+        stubTypeCode: stubType?.code ?? null,
+        stubTypeName: stubType?.name ?? null,
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    if (update.pollUpdates) {
+      try {
+        const pollCreation = await sock.getMessage(key);
+
+        if (pollCreation) {
+          const aggregatedVotes = getAggregateVotesInPollMessage({
+            message: pollCreation,
+            pollUpdates: update.pollUpdates,
+          });
+
+          logger.info('📊 Votos da enquete atualizados.', {
+            action: 'poll_votes_updated',
+            remoteJid: key.remoteJid,
+            messageId: key.id,
+            participant: key.participant || null,
+            votesCount: Object.values(aggregatedVotes || {}).reduce((a, b) => a + b, 0),
+            votes: aggregatedVotes,
+            timestamp: new Date().toISOString(),
+          });
+        } else {
+          logger.warn('⚠️ Mensagem da enquete não encontrada.', {
+            action: 'poll_message_not_found',
+            key,
+            timestamp: new Date().toISOString(),
+          });
+        }
+      } catch (error) {
+        logger.error('❌ Erro ao processar atualização de votos da enquete.', {
+          action: 'poll_update_error',
+          errorMessage: error.message,
+          stack: error.stack,
+          key,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Atualiza metadados de grupos no banco MySQL a partir dos eventos do Baileys.
+ * Processa alterações de grupo (título, descrição, proprietário e participantes)
+ * persistindo a versão consolidada no MySQL.
+ * @async
+ * @param {Array<import('@whiskeysockets/baileys').GroupUpdate>} updates - Eventos de atualização de grupos.
+ * @returns {Promise<void>} Conclusão das atualizações em lote.
+ */
+async function handleGroupUpdate(updates) {
+  await Promise.all(
+    updates.map(async (event) => {
+      try {
+        const groupId = event.id;
+        const oldData = (await findById('groups_metadata', groupId)) || {};
+        const updatedData = buildGroupMetadataFromUpdate(event, oldData);
+
+        await upsertGroupMetadata(groupId, updatedData, { mergeExisting: false });
+        invalidateCachedGroupMetadata(groupId);
+
+        const changedFields = Object.keys(event).filter((k) => event[k] !== oldData[k]);
+        logger.info('📦 Metadados do grupo atualizados', {
+          action: 'group_metadata_updated',
+          groupId,
+          groupName: updatedData.subject || oldData.subject || 'Desconhecido',
+          changedFields,
+          timestamp: new Date().toISOString(),
+        });
+      } catch (error) {
+        logger.error('❌ Erro ao atualizar metadados do grupo', {
+          action: 'group_metadata_update_error',
+          errorMessage: error.message,
+          stack: error.stack,
+          event,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }),
+  );
+}
+
+/**
+ * Retorna a instância atual do socket ativo do WhatsApp.
+ * @returns {import('@whiskeysockets/baileys').WASocket | null} O objeto socket do Baileys ativo ou `null` se não houver conexão ativa.
+ */
+export function getActiveSocket() {
+  logger.debug('🔍 Recuperando instância do socket ativo.', {
+    action: 'get_active_socket',
+    socketExists: !!activeSocket,
+    timestamp: new Date().toISOString(),
+  });
+  return activeSocket;
+}
+
+/**
+ * Executa um método centralizado no socket ativo, tratando erros e mapeando-os para respostas HTTP.
+ * @async
+ * @param {string} methodName - O nome do método a ser invocado no socket.
+ * @param {...any} args - Argumentos a serem repassados para o método do socket.
+ * @returns {Promise<any>} Uma promessa que resolve com o resultado do método do socket ou rejeita com um erro `Boom` em caso de falha.
+ * @throws {Boom} Retorna um erro HTTP 503 se o socket não estiver disponível, ou 501 se o método não existir.
+ */
+async function runControllerSocketMethod(methodName, ...args) {
+  try {
+    return await runActiveSocketMethod(methodName, ...args);
+  } catch (error) {
+    const message = String(error?.message || '');
+    if (message.includes('Socket do WhatsApp indisponível')) {
+      logger.warn('Socket ativo indisponível para operação.', {
+        action: methodName,
+        socketExists: !!activeSocket,
+        socketOpen: isSocketOpen(activeSocket),
+        timestamp: new Date().toISOString(),
+      });
+      throw new Boom('Socket do WhatsApp indisponível no momento.', { statusCode: 503 });
+    }
+    if (message.includes('não disponível no socket')) {
+      throw new Boom(`Método "${methodName}" não disponível neste socket.`, { statusCode: 501 });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Retorna as configurações de privacidade da conta do WhatsApp.
+ * @async
+ * @param {boolean} [force=false] - Se `true`, força um refresh das configurações no servidor.
+ * @returns {Promise<Record<string, string>>} Um objeto contendo as configurações de privacidade.
+ */
+export async function fetchPrivacySettings(force = false) {
+  return runControllerSocketMethod('fetchPrivacySettings', force);
+}
+
+/**
+ * Atualiza a configuração de privacidade para mensagens.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyMessagesValue} value - O novo valor da configuração de privacidade de mensagens.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateMessagesPrivacy(value) {
+  return runControllerSocketMethod('updateMessagesPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para chamadas.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyCallValue} value - O novo valor da configuração de privacidade de chamadas.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateCallPrivacy(value) {
+  return runControllerSocketMethod('updateCallPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para "visto por último".
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyValue} value - O novo valor da configuração de privacidade de "visto por último".
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateLastSeenPrivacy(value) {
+  return runControllerSocketMethod('updateLastSeenPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para status "online".
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyOnlineValue} value - O novo valor da configuração de privacidade de status "online".
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateOnlinePrivacy(value) {
+  return runControllerSocketMethod('updateOnlinePrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade da foto de perfil.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyValue} value - O novo valor da configuração de privacidade da foto de perfil.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateProfilePicturePrivacy(value) {
+  return runControllerSocketMethod('updateProfilePicturePrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para status.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyValue} value - O novo valor da configuração de privacidade de status.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateStatusPrivacy(value) {
+  return runControllerSocketMethod('updateStatusPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para confirmações de leitura.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAReadReceiptsValue} value - O novo valor da configuração de privacidade de confirmações de leitura.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateReadReceiptsPrivacy(value) {
+  return runControllerSocketMethod('updateReadReceiptsPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para adição em grupos.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPrivacyGroupAddValue} value - O novo valor da configuração de privacidade de adição em grupos.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateGroupsAddPrivacy(value) {
+  return runControllerSocketMethod('updateGroupsAddPrivacy', value);
+}
+
+/**
+ * Atualiza a configuração de privacidade para pré-visualização de links.
+ * @async
+ * @param {boolean} isPreviewsDisabled - Se `true`, desabilita a pré-visualização de links.
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateDisableLinkPreviewsPrivacy(isPreviewsDisabled) {
+  return runControllerSocketMethod('updateDisableLinkPreviewsPrivacy', isPreviewsDisabled);
+}
+
+/**
+ * Atualiza o modo padrão de mensagens temporárias para novos chats.
+ * @async
+ * @param {number} duration - A duração em segundos para as mensagens temporárias (ex: 0 para desativar, 7 * 24 * 60 * 60 para 7 dias).
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização é concluída.
+ */
+export async function updateDefaultDisappearingMode(duration) {
+  return runControllerSocketMethod('updateDefaultDisappearingMode', duration);
+}
+
+/**
+ * Envia uma atualização de presença para um chat ou para o status geral.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAPresence} type - O tipo de presença a ser enviado (e.g., 'available', 'composing', 'paused').
+ * @param {string} [toJid] - O JID do destinatário para quem a presença será enviada (opcional).
+ * @returns {Promise<void>} Uma promessa que resolve quando a atualização de presença é enviada.
+ */
+export async function sendPresenceUpdate(type, toJid) {
+  const normalizedType = normalizeWAPresence(type, 'available');
+  return runControllerSocketMethod('sendPresenceUpdate', normalizedType, toJid);
+}
+
+/**
+ * Inscreve-se na presença de um JID específico para receber atualizações de status.
+ * @async
+ * @param {string} toJid - O JID do contato ou grupo cuja presença será observada.
+ * @returns {Promise<void>} Uma promessa que resolve quando a inscrição é concluída.
+ */
+export async function presenceSubscribe(toJid) {
+  return runControllerSocketMethod('presenceSubscribe', toJid);
+}
+
+/**
+ * Executa uma modificação em um chat (e.g., arquivar, marcar como lido, mutar).
+ * @async
+ * @param {import('@whiskeysockets/baileys').ChatModification} mod - O objeto de modificação do chat.
+ * @param {string} jid - O JID do chat a ser modificado.
+ * @returns {Promise<void>} Uma promessa que resolve quando a modificação é aplicada.
+ */
+export async function chatModify(mod, jid) {
+  return runControllerSocketMethod('chatModify', mod, jid);
+}
+
+/**
+ * Atalho para arquivar ou desarquivar um chat.
+ * @async
+ * @param {string} jid - O JID do chat.
+ * @param {Array<import('@whiskeysockets/baileys').proto.IWebMessageInfo>} [lastMessages=[]] - Últimas mensagens do chat (opcional, para contexto).
+ * @param {boolean} [archive=true] - Se `true`, arquiva o chat; se `false`, desarquiva.
+ * @returns {Promise<void>} Uma promessa que resolve quando o chat é arquivado/desarquivado.
+ */
+export async function setChatArchived(jid, lastMessages = [], archive = true) {
+  return chatModify({ archive, lastMessages }, jid);
+}
+
+/**
+ * Atalho para marcar um chat como lido ou não lido.
+ * @async
+ * @param {string} jid - O JID do chat.
+ * @param {Array<import('@whiskeysockets/baileys').proto.IWebMessageInfo>} [lastMessages=[]] - Últimas mensagens do chat (opcional, para contexto).
+ * @param {boolean} [markRead=true] - Se `true`, marca o chat como lido; se `false`, marca como não lido.
+ * @returns {Promise<void>} Uma promessa que resolve quando o chat é marcado como lido/não lido.
+ */
+export async function setChatRead(jid, lastMessages = [], markRead = true) {
+  return chatModify({ markRead, lastMessages }, jid);
+}
+
+/**
+ * Atalho para mutar ou desmutar um chat.
+ * @async
+ * @param {string} jid - O JID do chat.
+ * @param {number|null} muteMs - A duração do mute em milissegundos. Use `null` ou `0` para desmutar.
+ * @returns {Promise<void>} Uma promessa que resolve quando o chat é mutado/desmutado.
+ */
+export async function setChatMute(jid, muteMs) {
+  return chatModify({ mute: muteMs }, jid);
+}
+
+/**
+ * Busca um histórico de mensagens sob demanda para um chat específico.
+ * @async
+ * @param {number} count - A quantidade de mensagens a serem solicitadas.
+ * @param {import('@whiskeysockets/baileys').WAMessageKey} oldestMsgKey - A chave da mensagem mais antiga conhecida para iniciar a busca.
+ * @param {number|import('long').default} oldestMsgTimestamp - O timestamp da mensagem mais antiga conhecida.
+ * @returns {Promise<string>} Uma promessa que resolve com o ID da requisição da operação.
+ */
+export async function fetchMessageHistory(count, oldestMsgKey, oldestMsgTimestamp) {
+  return runControllerSocketMethod('fetchMessageHistory', count, oldestMsgKey, oldestMsgTimestamp);
+}
+
+/**
+ * Solicita o reenvio de um placeholder para uma mensagem indisponível.
+ * @async
+ * @param {import('@whiskeysockets/baileys').WAMessageKey} messageKey - A chave da mensagem para a qual o placeholder deve ser reenviado.
+ * @param {Partial<import('@whiskeysockets/baileys').WAMessage>} [msgData] - Dados auxiliares da mensagem (opcional).
+ * @returns {Promise<string|undefined>} Uma promessa que resolve com um ID de string ou `undefined`.
+ */
+export async function requestPlaceholderResend(messageKey, msgData) {
+  return runControllerSocketMethod('requestPlaceholderResend', messageKey, msgData);
+}
+
+/**
+ * Rejeita uma chamada recebida no WhatsApp.
+ * @async
+ * @param {string} callId - O ID da chamada a ser rejeitada.
+ * @param {string} callFrom - O JID do originador da chamada.
+ * @returns {Promise<void>} Uma promessa que resolve quando a chamada é rejeitada.
+ */
+export async function rejectCall(callId, callFrom) {
+  return runControllerSocketMethod('rejectCall', callId, callFrom);
+}
+
+/**
+ * Força uma nova tentativa de conexão ao WhatsApp.
+ * Encerra o socket ativo atual, se existir, para disparar a lógica de reconexão.
+ * Se nenhum socket estiver ativo, inicia uma nova conexão.
+ * @async
+ * @returns {Promise<void>} Uma promessa que resolve quando o fluxo de reconexão é iniciado ou uma nova conexão é tentada.
+ */
+export async function reconnectToWhatsApp() {
+  // eslint-disable-next-line no-undef
+  if (activeSocket && activeSocket.ws?.readyState === WebSocket.OPEN) {
+    logger.info('♻️ Forçando fechamento do socket para reconectar...', {
+      action: 'force_reconnect',
+      timestamp: new Date().toISOString(),
+    });
+    activeSocket.ws.close();
+  } else {
+    logger.warn('⚠️ Nenhum socket ativo detectado. Iniciando nova conexão manualmente.', {
+      action: 'reconnect_no_active_socket',
+      timestamp: new Date().toISOString(),
+    });
+    await connectToWhatsApp();
+  }
+}
+
+if (process.argv[1] === __filename) {
+  logger.info('🚀 Socket Controller iniciado diretamente via CLI.', {
+    action: 'module_direct_execution',
+    timestamp: new Date().toISOString(),
+  });
+
+  connectToWhatsApp().catch((err) => {
+    logger.error('❌ Falha crítica ao tentar iniciar conexão via execução direta.', {
+      action: 'direct_connection_failure',
+      errorMessage: err.message,
+      stack: err.stack,
+      timestamp: new Date().toISOString(),
+    });
+    process.exit(1);
+  });
+}