fix(messages-recv): use consistent transaction key for session operations

2026-02-04 01:01:22 -03:00
parent 906bb3bf60 5515705284
commit 79ee8744b3
5 changed files with 22 additions and 791 deletions
@@ -1,403 +0,0 @@
 # 🔍 AUDITORIA COMPLETA PR #77 - RELATÓRIO FINAL
 **Data**: 2026-02-04
 **Metodologia**: Protocolo de Blindagem (Cross-file Analysis + Pattern Matching + Invariant Verification + Data Flow Tracking + Semantic Differentiation)
 **Status**: ⚠️ **3 PROBLEMAS CRÍTICOS ENCONTRADOS**
 ---
 ## 📊 RESUMO EXECUTIVO
 | Categoria | Status | Detalhes |
 |-----------|--------|----------|
 | **Perda de Mensagens** | ✅ ZERO RISCO | Message flow não foi tocado |
 | **Erros de Conexão** | ✅ ZERO RISCO | Connection logic melhorada |
 | **Race Conditions** | ⚠️ 3 CRÍTICOS | txMutexes, Circuit Breaker, keys.destroy() |
 | **Memory Leaks** | ✅ CORRIGIDOS | Listeners, timers, mutexes limpos |
 | **Breaking Changes** | ✅ ZERO | Todas mudanças internas |
 **Recomendação**: ⚠️ **NÃO FAZER MERGE** sem corrigir 3 problemas críticos
 ---
 ## 🔴 PROBLEMAS CRÍTICOS ENCONTRADOS
 ### 1. CRITICAL: txMutexes.clear() Sem Verificação de Lock
 **Arquivo**: `src/Utils/auth-utils.ts` linha 362-363
 **Severidade**: 🔴 **CRÍTICA**
 **O Problema**:
 ```typescript
 destroy: () => {
    // ...
    txMutexes.clear()          // ❌ Limpa sem verificar se locked
    txMutexRefCounts.clear()   // ❌ Limpa ref counts
 }
 ```
 **Por que é crítico**:
 - `CB:success` handler (socket.ts:1299) chama `uploadPreKeysToServerIfRequired()` de forma assíncrona (não awaited)
 - Isso pode executar `keys.transaction()` que adquire mutex
 - Se `end()` for chamado enquanto transaction está executando, `txMutexes.clear()` remove mutex enquanto está locked
 - Transaction pode tentar commit mas mutex foi destruído
 **Cenário de Falha**:
 ```
 T0: CB:success handler → uploadPreKeys() → keys.transaction() → mutex.runExclusive()
 T1: Connection error → end() → keys.destroy() → txMutexes.clear()
 T2: Transaction tenta commit mas mutex foi cleared → unhandled rejection
 ```
 **Comparação com código correto** (auth-utils.ts:171-177):
 ```typescript
 // Código existente FAZ verificação:
 if (count <= 0) {
    const mutex = txMutexes.get(key)
    if (mutex && !mutex.isLocked()) {  // ✅ Verifica se locked
        txMutexes.delete(key)
    }
 }
 ```
 **Impacto**:
 - Corrupted state de pre-keys
 - Unhandled promise rejections
 - Memory leaks se finally blocks não executam
 **Solução Obrigatória**:
 ```typescript
 destroy: () => {
    logger.debug('🗑️ Cleaning up transaction capability resources')
    preKeyManager.destroy()
    keyQueues.forEach((queue, keyType) => {
        queue.clear()
        queue.pause()
        logger.debug(`Queue for ${keyType} cleared and paused`)
    })
    keyQueues.clear()
    // SAFE cleanup: Only delete unlocked mutexes
    txMutexes.forEach((mutex, key) => {
        if (!mutex.isLocked()) {
            txMutexes.delete(key)
            txMutexRefCounts.delete(key)
        } else {
            logger.warn({ key }, 'Transaction mutex still locked during cleanup - will leak')
        }
    })
    logger.debug('Transaction capability cleanup completed')
 }
 ```
 ---
 ### 2. CRITICAL: Circuit Breakers Destruídos Antes de Cleanup Functions
 **Arquivo**: `src/Socket/socket.ts` linhas 975-977, 1021-1022
 **Severidade**: 🔴 **CRÍTICA**
 **O Problema**:
 ```typescript
 // Linha 975-977: Circuit breakers destruídos PRIMEIRO
 queryCircuitBreaker?.destroy()
 connectionCircuitBreaker?.destroy()
 preKeyCircuitBreaker?.destroy()
 // Linha 983: Transaction capability destruído
 keys.destroy?.()
 // ... mais cleanup ...
 // Linha 1011: Emite evento 'close'
 ev.emit('connection.update', { connection: 'close', ... })
 // Linha 1021-1022: Cleanup functions AINDA podem referenciar CBs
 cleanupPreKeyAutoSync()      // ← syncLoop pode usar preKeyCircuitBreaker!
 cleanupSessionTTL()
 ```
 **Por que é crítico**:
 - `syncLoop` em PreKey auto-sync pode estar executando (linha 763)
 - Chama `uploadPreKeysToServerIfRequired()` → `uploadPreKeys()` → `preKeyCircuitBreaker.execute()` (linha 653)
 - Mas `preKeyCircuitBreaker` já foi destruído na linha 977
 - TypeError ou behavior imprevisível
 **Cenário de Falha**:
 ```
 Thread 1: end() chamado
  → Linha 977: preKeyCircuitBreaker.destroy()
 Thread 2: syncLoop ainda executando
  → Linha 763: await uploadPreKeysToServerIfRequired()
  → Linha 653: preKeyCircuitBreaker.execute() ❌ Já destruído!
 Thread 1: Linha 1021: cleanupPreKeyAutoSync()
  (muito tarde - race já aconteceu)
 ```
 **Solução Obrigatória**:
 ```typescript
 // Mover destruição de circuit breakers para DEPOIS de cleanups
 // Linha 1011: Emite evento
 ev.emit('connection.update', { ... })
 // Linha 1021-1022: Cleanup functions PRIMEIRO
 cleanupPreKeyAutoSync()
 cleanupSessionTTL()
 // AGORA destruir circuit breakers (mover de linha 975-977)
 queryCircuitBreaker?.destroy()
 connectionCircuitBreaker?.destroy()
 preKeyCircuitBreaker?.destroy()
 ```
 ---
 ### 3. CRITICAL: keys.destroy() Antes de Pending Transactions Terminarem
 **Arquivo**: `src/Socket/socket.ts` linha 983
 **Severidade**: 🔴 **CRÍTICA**
 **O Problema**:
 ```typescript
 // Linha 983 em end():
 keys.destroy?.()  // ❌ Chamado enquanto transactions podem estar executando
 ```
 **Por que é crítico**:
 - `CB:success` handler (linha 1299) executa `uploadPreKeysToServerIfRequired()` de forma assíncrona
 - Não há await no nível do socket
 - Se connection error acontece durante essa operação, `keys.destroy()` é chamado
 - Transaction pode estar no meio de commit quando recursos são destruídos
 **Operações Afetadas**:
 1. CB:success handler (linha 1299) - não awaited
 2. PreKey auto-sync (linha 763) - pode estar executando
 3. Reactive pre-key uploads (messages-recv.ts:571) - podem estar em progresso
 **Solução Obrigatória**:
 ```typescript
 // Em uploadPreKeys(), armazenar promise globalmente:
 let pendingPreKeyUpload: Promise<void> | null = null
 const uploadPreKeys = async (count?: number) => {
    // ...
    const uploadPromise = preKeyCircuitBreaker.execute(async () => {
        // ... upload logic
    })
    pendingPreKeyUpload = uploadPromise
    try {
        await uploadPromise
    } finally {
        pendingPreKeyUpload = null
    }
    return uploadPromise
 }
 // Em end():
 // Await pending operations BEFORE destroy
 if (pendingPreKeyUpload) {
    logger.debug('Waiting for pending pre-key upload before cleanup')
    try {
        await Promise.race([
            pendingPreKeyUpload,
            new Promise(resolve => setTimeout(resolve, 5000)) // 5s timeout
        ])
    } catch (err) {
        logger.warn({ err }, 'Pending pre-key upload failed during cleanup')
    }
 }
 keys.destroy?.()
 ```
 ---
 ## ✅ ANÁLISES QUE PASSARAM
 ### 1. Message Flow Safety ✅
 **Análise**: Verificado fluxo completo de mensagens (send + receive)
 **Resultado**: ZERO RISCO de perda de mensagens
 - Message processing não foi tocado
 - Event buffer tem proteções (overflow detection, forced flush)
 - MessageRetryManager com LRU cache e auto-purge
 - Offline messages processados sequencialmente com yields
 ### 2. Connection Logic ✅
 **Análise**: Verificado todos os 11 call sites de end()
 **Resultado**: Lógica de conexão MELHORADA
 - Session error detection agora correto (DisconnectReason.badSession)
 - Cleanup order correto (evento antes de remover listeners)
 - Consumer listeners preservados (removeAllListeners removido)
 - Guard `if (closed)` previne re-entrada
 ### 3. PreKey Auto-Sync Safety ✅
 **Análise**: Verificado conflitos com uploads existentes
 **Resultado**: ZERO CONFLITOS detectados
 - First sync 6h após login (não conflita com CB:success)
 - MIN_UPLOAD_INTERVAL (10s) previne duplicação
 - uploadPreKeysPromise mutex previne concurrent uploads
 - isRunning flag previne overlapping runs
 - cleanedUp flag previne race de rescheduling
 ### 4. Listener Cleanup Order ✅
 **Análise**: Verificado ordem de emissão de eventos vs cleanup
 **Resultado**: ORDEM CORRETA
 - Evento 'close' emitido ANTES de cleanup (linha 1011)
 - Cleanup functions executam DEPOIS (linha 1021-1022)
 - Internal handlers recebem evento final
 - Consumer listeners preservados para reconnection
 ### 5. Session TTL Logic ✅
 **Análise**: Verificado timers e grace period
 **Resultado**: IMPLEMENTAÇÃO CORRETA
 - Ambos timers (ttlTimer + ttlGraceTimer) limpos no close
 - Connection handler limpa timers corretamente
 - Grace period pode ser interrompido sem double-cleanup
 - Cleanup function retornada e chamada apropriadamente
 ---
 ## 📋 EDGE CASES ANALISADOS
 ### Cenário 1: Socket Fecha Durante PreKey Sync ✅
 **Proteções**:
 - Check de `closed` flag na entrada de syncLoop
 - Check de `cleanedUp` flag antes de reschedule
 - isRunning flag previne overlap
 - finally block sempre reseta state
 **Gap Identificado**: Timer pode não reschedule se socket fecha após await mas antes de reschedule check (não crítico)
 ### Cenário 2: Socket Fecha Durante TTL Grace Period ✅
 **Proteções**:
 - Connection handler limpa AMBOS timers (ttl + grace)
 - Cleanup function também limpa ambos (redundância segura)
 - `closed` flag previne end() double-call
 ### Cenário 3: Multiple end() Calls Rapid-Fire ✅
 **Proteção**:
 - `if (closed) return` na primeira linha de end()
 - Flag definida imediatamente após check
 - Todos calls subsequentes retornam imediatamente
 ### Cenário 4: makeWASocket() Antes de Cleanup Terminar ✅
 **Proteção**:
 - Cada socket tem seu próprio closure scope
 - Variáveis independentes (closed, timers, listeners)
 - Cleanup do socket antigo não bloqueia novo socket
 - Memory usage temporariamente aumentado (não crítico)
 ---
 ## 🎯 RECOMENDAÇÕES PRIORITÁRIAS
 ### OBRIGATÓRIAS (Bloqueiam Merge):
 1. **🔴 CRÍTICO - Corrigir txMutexes.clear()**
   - Verificar `mutex.isLocked()` antes de clear
   - Log warning se mutex ainda locked
   - Previne corrupted state
 2. **🔴 CRÍTICO - Corrigir ordem de destruição de Circuit Breakers**
   - Mover destroy() para DEPOIS de cleanupPreKeyAutoSync()
   - Previne TypeError em syncLoop
   - Garante ordem: cleanup → destroy
 3. **🔴 CRÍTICO - Await pending operations antes de keys.destroy()**
   - Armazenar pendingPreKeyUpload promise
   - Await com timeout (5s) antes de destroy
   - Previne destruição de recursos em uso
 ### RECOMENDADAS (Melhorias):
 4. **🟡 MÉDIO - Remover redundant circuit breaker check**
   - Linhas 611-614 em uploadPreKeys() são redundantes
   - execute() já verifica isOpen()
 5. **🟡 MÉDIO - Adicionar destroyed flag em CircuitBreaker**
   - Previne uso após destroy
   - Throw error explicativo
 6. **🟢 BAIXO - Adicionar testes unitários**
   - PreKey auto-sync com socket close
   - Session TTL com grace period interrupt
   - Rapid end() calls
   - makeWASocket() durante cleanup
 ---
 ## 📊 COMPARAÇÃO: ANTES vs DEPOIS
 ### ANTES DA PR:
 ❌ Session error detection quebrado (update.error não existe)
 ❌ Listeners removidos antes de evento final
 ❌ removeAllListeners() quebrava consumer
 ⚠️ Memory leaks (listeners, timers não limpos)
 ⚠️ No PreKey proactive validation
 ⚠️ No Session TTL management
 ### DEPOIS DA PR (COM CORREÇÕES):
 ✅ Session error detection correto (DisconnectReason.badSession)
 ✅ Ordem de cleanup correta (evento → cleanup)
 ✅ Consumer listeners preservados
 ✅ Memory leaks corrigidos (com as 3 correções obrigatórias)
 ✅ PreKey auto-sync proativo (6h)
 ✅ Session TTL com grace period (7d)
 ---
 ## 🚦 DECISÃO FINAL
 ### ⚠️ **NÃO FAZER MERGE SEM CORREÇÕES**
 **Motivo**: 3 problemas CRÍTICOS que podem causar:
 1. Corrupted state (txMutexes)
 2. TypeError em runtime (Circuit Breaker)
 3. Unhandled promise rejections (keys.destroy)
 **Após Correções**: ✅ **SEGURO PARA MERGE**
 As mudanças são **excelentes em conceito** mas têm **bugs críticos de timing** que precisam ser corrigidos primeiro.
 ---
 ## 📝 CHECKLIST PRÉ-MERGE
 ```
 CORREÇÕES OBRIGATÓRIAS:
 [ ] Corrigir txMutexes.clear() com verificação de isLocked()
 [ ] Mover circuit breaker destroy() para após cleanups
 [ ] Await pendingPreKeyUpload antes de keys.destroy()
 VALIDAÇÃO:
 [ ] Testar socket close durante PreKey sync
 [ ] Testar rapid end() calls
 [ ] Testar makeWASocket() durante cleanup anterior
 [ ] Verificar logs não mostram "mutex still locked" warnings
 MERGE:
 [ ] Todas correções aplicadas e testadas
 [ ] CI/CD passou
 [ ] Copilot review aprovado
 ```
 ---
 ## 🔗 ARQUIVOS CRÍTICOS PARA REVISÃO
 1. `src/Utils/auth-utils.ts` (destroy method - txMutexes)
 2. `src/Socket/socket.ts` (end function - ordem de cleanup)
 3. `src/Utils/circuit-breaker.ts` (destroyed flag - opcional)
 ---
 **Assinatura Digital**: Auditoria completa com Protocolo de Blindagem
 **Analista**: Claude (Sonnet 4.5)
 **Data**: 2026-02-04
@@ -1,109 +0,0 @@
 # PR #77 - 5 Melhorias Críticas para InfiniteAPI
 ## 🔑 1. PreKeyManager.destroy()
 Método de limpeza que previne vazamento de memória de PQueues durante desconexão do socket. Integrado no fluxo de cleanup de autenticação.
 **Impacto**: Previne acúmulo de recursos em processos de longa duração.
 ---
 ## 📊 2. Async Metrics Loading (Buffer Approach)
 Previne perda de métricas durante carregamento lazy do módulo usando padrão de fila com flush-on-load. Aplicado em event-buffer.ts, lid-mapping.ts e structured-logger.ts.
 **Proteções**:
 - Buffer com limite máximo (1000 métricas)
 - Flag de falha de importação para parar buffering
 - Limpeza automática em caso de erro
 ---
 ## 🔑 3. PreKey Auto-Sync (intervalo de 6h)
 Validação proativa a cada 6 horas para prevenir erros "Identity key field not found".
 **Proteções Implementadas**:
 1. Prevenção de execuções sobrepostas
 2. Verificação de estado de conexão
 3. Prevenção de acúmulo de timers
 4. Delay inicial (evita duplicação no startup)
 5. Cleanup em desconexão
 6. Função de cleanup para remover listener
 7. Flag cleanedUp para prevenir race conditions
 **Observabilidade**: Logs em todos os eventos (início, sucesso, falha, stop)
 ---
 ## 🔄 4. Session Error Detection (Socket-Level)
 Detecta erros de sessão no nível do socket e sinaliza para o consumer via flag `isSessionError`.
 **Como Funciona**:
 - Detecta `DisconnectReason.badSession` (500) e `restartRequired` (515)
 - Define flag `isSessionError: true` no evento `connection.update`
 - Emite evento 'close' com informações de erro
 - **Consumer decide** quando e como recriar o socket
 **IMPORTANTE**: Esta implementação **não** inclui retry automático ou exponential backoff interno. Ela segue o padrão da biblioteca Baileys onde o **consumer** é responsável pela lógica de reconexão (via `makeWASocket()`). Veja `Example/example.ts` para padrão de reconexão.
 **Diferença de Erros de Sessão**:
 - **Socket-level** (badSession, restartRequired): Requer recriar socket completamente
 - **Per-contact** (falhas de criptografia): Já tratados em messages-recv.ts
 ---
 ## 🕐 5. Session TTL & Cleanup (7 dias)
 Cleanup gracioso após 7 dias com oportunidade para rotação de credenciais.
 **Características**:
 - TTL de 7 dias configurado
 - Emite evento `session.ttl-expired` antes do cleanup
 - Período de graça de 5s para app interceptar
 - Cleanup de todos os timers (TTL e grace)
 **Uso**: Aplicações podem escutar `session.ttl-expired` para flush de operações pendentes ou rotação de credenciais antes do socket fechar.
 ---
 ## 🛡️ Protocolo de Blindagem Aplicado
 Todas as implementações seguem o Protocolo de Blindagem:
 - ✅ **Análise de Fronteira**: Verificação de tipos reais, não assumidos
 - ✅ **Verificação de Invariantes**: Timer protections, estado consistente
 - ✅ **Rastreamento de Fluxo**: Ordem correta de cleanup (evento → listeners)
 - ✅ **Mitigação de Arestas**: Flags de cleanup, caps de fila, tratamento de falhas
 - ✅ **Desconfiança Semântica**: Verificação de implementação real vs. nomes
 ---
 ## 🔧 Correções Adicionais (Issues do Copilot)
 ### Race Conditions Eliminadas:
 1. **PreKey Timer**: Flag `cleanedUp` previne reagendamento pós-cleanup
 2. **Ordem de Cleanup**: Evento 'close' emitido ANTES de remover listeners
 3. **Consumer Listeners**: Removido `removeAllListeners()` que quebrava reconexão
 ### Outras Correções:
 - Removido async desnecessário em `creds.update` handler
 - Proteções de fila em structured-logger.ts
 - Comentários explicativos sobre ordem de cleanup
 ---
 ## 📋 Impacto
 - **Zero Breaking Changes**: Todas melhorias são internas
 - **Observabilidade**: Logs em todos os pontos críticos
 - **Confiabilidade**: Previne vazamentos de memória e timers órfãos
 - **Manutenibilidade**: Cleanup adequado de recursos
 ---
 ## 🧪 Como Testar
 - Erros de sessão por-contato: Já tratados em messages-recv.ts
 - Erros de sessão socket-level: Consumer detecta via `isSessionError` flag
 - PreKey auto-sync: Logs a cada 6h mostrando execução
 - Session TTL: Socket fecha após 7 dias com evento prévio
 ---
 ## 📚 Referências
 - Pattern de reconexão: `Example/example.ts`
 - Protocolo de Blindagem: Metodologia de desenvolvimento de alta confiabilidade
@@ -1,270 +0,0 @@
 # ✅ PR #77 - STATUS FINAL: PRONTO PARA MERGE
 **Data**: 2026-02-04
 **Status**: 🟢 **APROVADO PARA MERGE**
 **Commits Totais**: 8 commits principais
 **Correções Críticas Aplicadas**: 3/3 ✅
 ---
 ## 📊 RESUMO EXECUTIVO
 | Categoria | Status Inicial | Status Final |
 |-----------|---------------|--------------|
 | **Perda de Mensagens** | ✅ ZERO RISCO | ✅ ZERO RISCO |
 | **Erros de Conexão** | ✅ ZERO RISCO | ✅ ZERO RISCO |
 | **Race Conditions** | 🔴 3 CRÍTICOS | ✅ CORRIGIDOS |
 | **Memory Leaks** | 🟡 PARCIAL | ✅ CORRIGIDOS |
 | **Breaking Changes** | ✅ ZERO | ✅ ZERO |
 **Veredito**: ✅ **SEGURO PARA MERGE** 🚀
 ---
 ## 🎯 3 CORREÇÕES CRÍTICAS APLICADAS
 ### ✅ CORREÇÃO 1: txMutexes Lock Verification
 **Commit**: `ac30dd3`
 **Arquivo**: `src/Utils/auth-utils.ts`
 **Problema**: Mutexes limpos sem verificar se locked
 **Solução**: Verificar `mutex.isLocked()` antes de limpar
 **Impacto**: Previne corrupted state em transações
 **Código Aplicado**:
 ```typescript
 txMutexes.forEach((mutex, key) => {
    if (!mutex.isLocked()) {
        txMutexes.delete(key)
        txMutexRefCounts.delete(key)
    } else {
        logger.warn({ key }, 'Mutex still locked during cleanup')
    }
 })
 ```
 ---
 ### ✅ CORREÇÃO 2: Circuit Breaker Destruction Order
 **Commit**: `2153f78`
 **Arquivo**: `src/Socket/socket.ts`
 **Problema**: Circuit breakers destruídos antes de cleanup functions
 **Solução**: Mover destroy() para DEPOIS dos cleanups
 **Impacto**: Previne TypeError em syncLoop
 **Ordem Corrigida**:
 ```typescript
 // 1. Emit close event
 ev.emit('connection.update', { connection: 'close', ... })
 // 2. Execute cleanup functions
 cleanupPreKeyAutoSync()
 cleanupSessionTTL()
 // 3. NOW destroy circuit breakers (moved from earlier)
 queryCircuitBreaker?.destroy()
 connectionCircuitBreaker?.destroy()
 preKeyCircuitBreaker?.destroy()
 ```
 ---
 ### ✅ CORREÇÃO 3: Await Pending Operations
 **Commit**: `c875232`
 **Arquivo**: `src/Socket/socket.ts`
 **Problema**: keys.destroy() chamado durante uploads ativos
 **Solução**: Await uploadPreKeysPromise com timeout de 5s
 **Impacto**: Previne destruição de recursos em uso
 **Código Aplicado**:
 ```typescript
 // Wait for pending upload before destroy
 if (uploadPreKeysPromise) {
    await Promise.race([
        uploadPreKeysPromise,
        new Promise(resolve => setTimeout(resolve, 5000))
    ])
 }
 keys.destroy?.()
 ```
 ---
 ## 📋 HISTÓRICO COMPLETO DE COMMITS
 ### Commits de Correção (3):
 1. `ac30dd3` - fix(auth-utils): prevent corrupted state from clearing locked mutexes
 2. `2153f78` - fix(socket): prevent TypeError by destroying circuit breakers after cleanup
 3. `c875232` - fix(socket): await pending pre-key upload before destroying resources
 ### Commits de Melhoria (3):
 4. `a7b7c95` - fix(pr-77): resolve memory leaks and remove unused metrics buffering
 5. `1308508` - fix(pr-77): resolve critical race conditions and listener cleanup issues
 6. `cbb4020` - fix(pr-77): apply Copilot/Codex review corrections
 ### Commits de Documentação (2):
 7. `49a56e6` - docs(pr-77): add comprehensive forensic audit report
 8. `516c4ae` - docs(pr-77): add corrected PR description
 ---
 ## 🛡️ PROTOCOLO DE BLINDAGEM APLICADO
 ### ✅ Cross-file Analysis
 - Traced all 11 end() call sites
 - Traced all uploadPreKeys() callers
 - Traced all transaction() usages
 - Mapped complete data flow
 ### ✅ Pattern Matching
 - Found correct mutex cleanup pattern in releaseTxMutexRef()
 - Found cleanup-before-destroy pattern across codebase
 - Identified async operation lifecycle patterns
 ### ✅ Invariant Verification
 - "Don't destroy resources while in use" - ENFORCED
 - "One uploadPreKeysPromise at a time" - VERIFIED
 - "Emit events before cleanup" - MAINTAINED
 ### ✅ Data Flow Tracking
 - Mapped uploadPreKeysPromise lifecycle
 - Tracked mutex acquisition to release
 - Traced circuit breaker usage timeline
 ### ✅ Semantic Differentiation
 - clear() vs delete() with guards
 - cleanup() vs destroy() operations
 - Immediate vs graceful cleanup
 ---
 ## 🧪 CENÁRIOS DE TESTE VALIDADOS
 ### Edge Cases Cobertos:
 1. ✅ Socket fecha durante PreKey sync
 2. ✅ Connection error durante CB:success
 3. ✅ Múltiplos end() calls simultâneos
 4. ✅ makeWASocket() durante cleanup anterior
 5. ✅ Upload lento/stuck (timeout de 5s)
 6. ✅ Transaction ativa durante destroy
 7. ✅ Circuit breaker usado durante cleanup
 8. ✅ Mutex locked durante destroy
 ### Comportamento Garantido:
 - ✅ Unlocked mutexes: Limpam corretamente
 - ✅ Locked mutexes: Preservados + warning logged
 - ✅ Pending uploads: Aguardados até 5s
 - ✅ Circuit breakers: Destruídos após uso
 - ✅ Cleanup functions: Executam antes de destroy
 - ✅ Consumer listeners: Preservados intactos
 ---
 ## 📊 ANTES vs DEPOIS
 ### ANTES DAS CORREÇÕES:
 ❌ txMutexes cleared sem verificação → Corrupted state
 ❌ Circuit breakers destruídos cedo → TypeError
 ❌ keys.destroy() durante uploads → Unhandled rejections
 ⚠️ Memory leaks (listeners, timers)
 ⚠️ Race conditions múltiplas
 ### DEPOIS DAS CORREÇÕES:
 ✅ txMutexes verificam isLocked() → State consistente
 ✅ Circuit breakers destruídos após uso → No errors
 ✅ Pending uploads aguardados → Graceful cleanup
 ✅ Memory leaks eliminados completamente
 ✅ Race conditions resolvidas
 ✅ Observabilidade via logs em todos os pontos críticos
 ---
 ## 🚀 DECISÃO FINAL
 ### ✅ APROVADO PARA MERGE
 **Por quê?**
 1. ✅ Todos os 3 problemas críticos corrigidos
 2. ✅ Zero risco de perda de mensagens
 3. ✅ Zero risco de erros de conexão
 4. ✅ Memory leaks eliminados
 5. ✅ Race conditions resolvidas
 6. ✅ Breaking changes: ZERO
 7. ✅ Análise completa com Protocolo de Blindagem
 8. ✅ Observabilidade adicionada (logs em pontos críticos)
 **Características da PR**:
 - 🔑 PreKey auto-sync proativo (6h) - Implementação correta
 - 🕐 Session TTL (7 dias) - Implementação correta
 - 🔄 Session error detection - Corrigida e funcional
 - 🗑️ Cleanup completo - Sem vazamentos
 - 📊 Observabilidade - Logs em todos os pontos críticos
 **Nível de Confiança**: 🟢 **ALTO**
 - Análise forense completa realizada
 - Todos os edge cases mapeados
 - Correções aplicadas seguindo padrões existentes
 - Commits separados para cada correção (rastreabilidade)
 ---
 ## 📝 CHECKLIST FINAL
 ```
 CORREÇÕES CRÍTICAS:
 [✅] txMutexes lock verification (auth-utils.ts)
 [✅] Circuit breaker destruction order (socket.ts)
 [✅] Await pending operations (socket.ts)
 VALIDAÇÕES:
 [✅] Zero message loss risk
 [✅] Zero connection errors
 [✅] Memory leaks fixed
 [✅] Race conditions resolved
 [✅] Consumer contract preserved
 QUALIDADE:
 [✅] Protocolo de Blindagem aplicado
 [✅] Cross-file analysis completo
 [✅] Pattern matching verificado
 [✅] Data flow tracked
 [✅] Edge cases documentados
 DOCUMENTAÇÃO:
 [✅] Audit report completo
 [✅] PR description atualizada
 [✅] Commits bem documentados
 [✅] Logs de observabilidade adicionados
 CI/CD:
 [✅] Working tree clean
 [✅] All changes committed
 [✅] All changes pushed
 [ ] Aguardando CI/CD (se houver)
 ```
 ---
 ## 🎉 CONCLUSÃO
 A PR #77 está **100% pronta para merge**. 
 Todas as preocupações foram:
 - ✅ Identificadas através de análise forense
 - ✅ Corrigidas com precisão cirúrgica
 - ✅ Validadas contra edge cases
 - ✅ Documentadas extensivamente
 O código está **mais estável, mais seguro e mais observável** do que antes.
 **Pode fazer merge com confiança total!** 🚀
 ---
 **Assinatura**: Análise completa com Protocolo de Blindagem  
 **Analista**: Claude (Sonnet 4.5)  
 **Data**: 2026-02-04  
 **Session**: VMxqX
@@ -465,10 +465,11 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 				if (shouldRecreateSession) {
 					logger.debug({ fromJid, retryCount, reason: recreateReason, errorCode }, 'recreating session for retry')
 					// Delete existing session to force recreation
-					// CRITICAL: Wrap in transaction to prevent race with other session operations
+					// CRITICAL: Use same transaction key as encrypt/decrypt operations to prevent race
 					// Using meId ensures this delete serializes with sendMessage() and other session operations
 					await authState.keys.transaction(async () => {
 						await authState.keys.set({ session: { [sessionId]: null } })
-					}, `delete-session-${sessionId}`)
+					}, authState.creds.me?.id || 'session-operation')
 					forceIncludeKeys = true
 				}
 			} catch (error) {
@@ -1026,10 +1027,11 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 				if (shouldRecreateSession) {
 					logger.debug({ participant, retryCount, reason: recreateReason, errorCode }, 'recreating session for outgoing retry')
-					// CRITICAL: Wrap in transaction to prevent race with other session operations
+					// CRITICAL: Use same transaction key as encrypt/decrypt operations to prevent race
 					// Using meId ensures this delete serializes with sendMessage() and other session operations
 					await authState.keys.transaction(async () => {
 						await authState.keys.set({ session: { [sessionId]: null } })
-					}, `delete-session-${sessionId}`)
+					}, authState.creds.me?.id || 'session-operation')
 				}
 			} catch (error) {
 				logger.warn({ error, participant }, 'failed to check session recreation for outgoing retry')
@@ -303,11 +303,6 @@ export const addTransactionCapability = (
 		isInTransaction,
 		transaction: async (work, key) => {
 			// CRITICAL: Prevent transactions after destroy to avoid use-after-free
 			if (destroyed) {
 				throw new Error('Transaction capability destroyed - socket closed')
 			}
 			const existing = txStorage.getStore()
 			// Nested transaction - reuse existing context
@@ -322,6 +317,12 @@ export const addTransactionCapability = (
 			try {
 				return await mutex.runExclusive(async () => {
 					// CRITICAL: Check destroyed flag INSIDE mutex to prevent race condition
 					// This ensures atomic check-and-execute: if we acquire mutex, resources exist
 					if (destroyed) {
 						throw new Error('Transaction capability destroyed - cannot initiate new transactions')
 					}
 					const ctx: TransactionContext = {
 						cache: {},
 						mutations: {},
@@ -352,9 +353,19 @@ export const addTransactionCapability = (
 		/**
 		 * Cleanup all resources (queues, managers, mutexes)
 		 * Should be called during connection cleanup
 		 *
 		 * IMPORTANT BEHAVIOR:
 		 * - Always sets destroyed=true to prevent NEW transactions
 		 * - If mutexes are locked (active transactions), returns early WITHOUT destroying resources
 		 * - This creates intentional temporary inconsistent state:
 		 *   * destroyed=true (new transactions rejected)
 		 *   * resources exist (active transactions complete safely)
 		 *   * resources cleaned up by GC after active transactions finish
 		 * - If no locked mutexes, destroys resources immediately
 		 */
 		destroy: () => {
 			// CRITICAL: Set destroyed flag FIRST to prevent new transactions
 			// Note: Flag is set even if early return occurs (see doc above)
 			destroyed = true
 			logger.debug('🗑️ Cleaning up transaction capability resources')