Duas duplicações que encontrei mexendo no atendimento de um self-host

[Gervanno]

Fala, Rafa!

Tudo bem?

Investigando uma reclamação de duplicação de resposta numa instalação minha, encontrei duas causas distintas — sem relação com ai_dispatch_mode, isso eu já descartei. São as duas em lib/waha/ingest.ts e lib/agent-engine/edge/crm/drain.ts. Anonimizei os dados de cliente antes de escrever aqui.

1. Eco do próprio envio duplica a linha em messages

Em handleOutboundFromUserPhone (~linhas 561-629), o comentário que já está no código ("ECO DO PRÓPRIO ENVIO — não duplicar") descreve certo o problema, mas a solução não fecha a janela: o dedup é SELECT ... WHERE external_id IN (fullId, bareId) e só depois INSERT — não atômico. Quando o eco do WAHA chega perto o suficiente do insert que o próprio envio (composer/IA) já fez, o SELECT roda antes de esse insert commitar, e as duas linhas nascem. O unique(organization_id, external_id) não pega isso como rede de segurança porque os dois lados gravam formas diferentes do mesmo id — o envio grava o bare (3EB0…), o eco grava o composto (true_<chat>_3EB0…) — strings literalmente diferentes, então o 23505 nunca dispara.

Vi isso em produção: dois pares de linhas duplicadas, mesmo corpo, mesma conversa, ~1.3s e ~2s de diferença entre a linha sent_via='ai' (external_id bare) e a sent_via='external_device' (external_id composto terminando no mesmo bare). Não é envio duplicado pro cliente — é o mesmo WhatsApp físico — mas duplica na timeline do CRM, e infla qualquer métrica que conte linhas de messages.

Sugestão: gravar bareWaMessageId(p.id) como external_id neste insert também (em vez do p.id cru). As duas trilhas de escrita passam a usar a mesma string de identidade, e o unique(organization_id, external_id) + captura de 23505 — o padrão que o próprio arquivo já usa no handler de inbound — fecha o dedup sem precisar do SELECT. O matching de ack (~linhas 667-677) já busca as duas formas, então acho que continua funcionando sem ajuste. Não mexe em schema.

2. Debounce de rajada inbound não é deslizante

Em drain.ts (coalescência ~linhas 252-264) e o comentário de intenção em lib/agent-engine/env.ts:69-70:

"Coalescência de rajada inbound: mensagens do MESMO contato dentro desta janela viram UM job (responder em rajada é gatilho de ban)."

A intenção é clara — e é anti-ban, o mesmo motivo do throttle de envio — mas a implementação não entrega isso. A checagem é status='pending' AND run_after > now() contra o job da PRIMEIRA mensagem. run_after = created_at + INBOUND_DEBOUNCE_MS (default 8000ms) é fixado na criação e nunca estendido quando chega mensagem nova. Numa rajada humana típica — bolhas de WhatsApp com 10-20s de intervalo, bem comum — cada mensagem que chega depois que o run_after do job anterior já passou não acha nada pra pegar carona e cria um job novo. O agente responde cada bolha separadamente.

Vi isso também em produção: 3 mensagens do mesmo contato em ~30s (gaps de ~12.1s e ~17.5s), nenhuma coalesceu — 3 jobs inbound_turn, 3 respostas separadas em menos de 2 minutos, todas no mesmo assunto. É exatamente o cenário que o debounce existe pra evitar, só que escapando pela borda de fora da janela. Do lado do dono, parece "a IA respondendo em duplicidade".

Sugestão: quando uma mensagem encontra um job pendente pra coalescer (hoje só faz return 'processado'), também UPDATE job_queue SET run_after = now() + debounceMs WHERE id = ... — estendendo a janela a cada mensagem nova. Talvez valha um teto (uns 30-45s desde a primeira mensagem da rajada) pra não atrasar indefinidamente se o contato não parar de mandar mensagem. Mexe em roteamento/debounce, então por doutrina do próprio repo precisa de pnpm test:db local antes de mergear.

Sem pressa nas duas — só sinalizando o que achei. Se fizer sentido eu mando um PR pra alguma delas, me avisa. Valeu! 🙏

[melgarafael]

Obrigado, @Gervanno — as duas procedem, e confirmei cada peça no código. Régua: origin/main f9abedd.

(a) Eco do próprio envio duplica a linha em messages

O mecanismo que você descreve está certo:

• lib/waha/ingest.ts:639-651 — o dedup é check-then-act, não atômico: monta idCandidates e faz select ... in("external_id", idCandidates).limit(1), depois if (jaRegistrada) return.
• ingest.ts:679 — o eco grava o external_id na forma composta; app/api/v1/messages/_handler.ts:526 grava o bare.
• As duas strings são de fato diferentes (medido com o próprio bareWaMessageId sobre o payload real que lib/waha/message-id.ts documenta):

composto: true_250302204792918@lid_2A1B890FB8AA87730CBC
bare:     2A1B890FB8AA87730CBC                              iguais? false

• E a constraint que deveria ser a rede de segurança existe — messages_org_external_id_unique UNIQUE (organization_id, external_id) — mas não cobre este caminho, porque as duas trilhas gravam chaves diferentes. Você tinha razão em apontar que o unique não salva.

A ressalva que preciso registrar antes de qualquer PR, e que me fez não consertar já: o atalho óbvio — fazer o ingest gravar sempre o bare — melhora NOWEB e piora WEBJS. Sob WEBJS as duas trilhas hoje gravam a mesma string (lib/channels/adapters/waha.ts:24-31 e lib/waha/message-id.ts:16-17), então ali o unique é a rede de segurança e o 23505 dispara. Trocar para bare no ingest faria o eco gravar bare enquanto a linha do CRM segue com o composto, e a corrida voltaria para quem roda WEBJS — que é configuração suportada. O conserto certo normaliza os dois lados, não um.

(b) Debounce de rajada não é deslizante

Confirmado linha por linha:

• lib/agent-engine/edge/crm/drain.ts:252-259 — a carona só existe enquanto run_after > now();
• drain.ts:269 — o prazo é fixado uma vez, na criação, e nada o estende depois (grep run_after em lib/agent-engine só devolve o claim e o reagendamento de falha);
• lib/agent-engine/env.ts:71 — INBOUND_DEBOUNCE_MS default 8s, sob o comentário que promete "mensagens do MESMO contato dentro desta janela viram UM job".

Descartei a hipótese de haver coalescência escondida rio abaixo: queue.ts:96-104 dedupa só por source_event_id, e cada inbound gera evento distinto → job novo, sempre. O CLAIM_SQL serializa por contato, então os N jobs viram N respostas em sequência — que é exatamente o que você viu.

E aqui uma medição que derruba a correção intuitiva (fiz porque ela era a primeira coisa que eu ia escrever): estender o run_after do job pendente não resolve o caso que você relatou. Rodado contra um Postgres com a tabela real, no seu cenário (gap de 12,1s, debounce 8s):

job anterior já `running`        -> UPDATE 0
job `pending`, run_after vencido -> UPDATE 0
CONTROLE (gap 3s < debounce)     -> UPDATE 1, run_after estendido

Com gap maior que o debounce o job anterior já venceu ou já virou running — não há linha para estender. E com gap menor o código de hoje já coalesce. Ou seja: a janela deslizante precisa de um desenho diferente (estender também o running, ou re-enfileirar por contato), não de um UPDATE a mais.

Onde isso fica

As duas viram trabalho próprio, e não estão neste PR: (a) precisa normalizar os dois lados sem regredir WEBJS, e (b) precisa de desenho, não de patch. Deixo a issue aberta com o diagnóstico acima em vez de fechar com um conserto que eu não medi funcionando — o que valeria para (b) é justamente o que a medição derrubou.

Se quiser tocar alguma das duas, o material acima já é o ponto de partida, e eu reviso.

[melgarafael]

Desenho do conserto de (a), com uma armadilha que quase entrou

Voltei nesta com um ciclo de projeto + refutação. O conserto ficou desenhado e medido, mas não entra nesta rodada — explico no fim por quê.

A escolha

Normalizar no ponto de escrita: a cauda (bare) vira a forma canônica de messages.external_id do WhatsApp nas duas trilhas, por um método novo do seam (ChannelAdapter.canonicalExternalId), e o perdedor da corrida passa a tratar o 23505 em vez de ignorá-lo.

As alternativas caíram por medição, não por gosto:

• Reconstruir o composto nas duas trilhas (o inverso): o chat do eco vem do engine (@lid) e o do envio vem do nosso cadastro (@c.us) — a chave voltaria a divergir exatamente em quem tem contato @lid, que é a instalação de onde a issue veio.
• Normalizar na leitura: é o que o código já faz (ingest.ts:640, handleAck) e é o que falhou. Leitura não fecha fresta — entre o SELECT e o INSERT cabem dois RPCs.

Medido no banco de verdade (Postgres + PostgREST reais):

HOJE          SQLSTATE do insert do eco: 00000   -> 2 linhas na conversa
COM O PATCH   SQLSTATE do insert do eco: 23505   -> 1 linha

E um detalhe que decide o desenho: a constraint é DEFERRABLE, então a violação só estoura no COMMIT — o UPDATE sai 00000 e o SELECT dentro da transação já mostra o external_id gravado. Sem tratar isso, a linha volta a queued com a mensagem já entregue.

A armadilha — e é por isso que o passe adversarial existe

A primeira versão do patch blindava dois escritores da chave. São três: redriveQueued, em lib/agent-engine/edge/crm/session-reconciler.ts:199-203, cujo catch classifica a violação como "erro transiente — mantida queued".

Medido com o redriveQueued real, 3 tiques, mesma sequência nos dois mundos:

SEM o patch   tick1=1 tick2=0 tick3=0 | sendText ao cliente: 1 | status=sent
COM o patch   tick1=0 tick2=0 tick3=0 | sendText ao cliente: 3 | status=queued, external_id=null
              log x3: "watchdog: redrive com erro transiente — mantida queued"

Ou seja: o patch trocaria uma linha duplicada na tela por o cliente recebendo a mensagem de novo a cada tique, sem limite. É exatamente o desfecho que o CLAUDE.md fixa como doutrina — "não reenvia — envio em dobro é pior que não-envio" — e que o comentário do próprio patch declarava querer evitar. O conserto é tratar o 23505 ali também, fechando em sent sem a chave.

Por que não entra agora

Três motivos, e o terceiro é decisivo:

1. São 10 arquivos e uma migration com backfill, no caminho de envio de mensagem — o mais crítico do produto. Merece PR próprio e revisão isolada, não carona num PR de triagem.
2. A versão inicial foi refutada; a corrigida ainda não passou por um segundo passe adversarial completo.
3. O patch toca supabase/baseline.sql, e o baseline acabou de ser reescrito no conserto da BASELINE.SQL não idempotente #184 (ele virou re-aplicável de verdade). O apêndice precisa ser reconstruído sobre a nova forma antes de qualquer coisa.

O material medido fica registrado aqui para quem pegar — inclusive a armadilha, que é o que economiza o ciclo.