O commit atômico e por que a simulação não prova semântica de broker real

A pergunta que outbox.mjs responde é: como persistir "o resultado da extração existe" e "um evento avisando isso foi criado" de um jeito que nunca deixe só um dos dois acontecer? A resposta clássica, documentada pela AWS como transactional outbox pattern, é gravar as duas coisas na mesma transação de banco e deixar um processo separado (o relay) ler a tabela de outbox e publicar - se a transação falha, nenhum dos dois lado acontece; se ela commita, os dois aconteceram juntos, e o relay garante a entrega do evento de forma desacoplada do sucesso da publicação em si.

Neste capítulo, "mesma transação" é simulado como uma única chamada síncrona de JavaScript sem await no meio - o que já é verdade o bastante para provar a lógica de dedupe e conflito, mas não prova o que acontece quando o processo morre a meio de um COMMIT real em disco, nem o que acontece se duas conexões de banco competem pela mesma linha. examples/pipeline-runbook.md lista explicitamente essa lacuna e o roteiro para fechá-la com PostgreSQL de verdade (não executado nesta sessão - ver seção de custo/reversibilidade). O ponto pedagógico sobrevive à simplificação: o bug que o outbox previne (perder o evento, ou publicar um evento para uma transação que fez rollback) é real e documentado independentemente da tecnologia escolhida para implementá-lo.

O cenário de abertura, testado de ponta a ponta em crash-recovery.test.mjs:

assert.throws(() => worker.processOnce(0, createCrashInjector('after_commit_before_ack')), CrashSimulated);
const resumed = worker.processOnce(5000); // "novo processo", bem depois do lease expirar
assert.equal(resumed.outcome, 'acked');
assert.equal(resumed.deduped, true, 'segundo commit precisa dedupar, não criar segundo evento');
assert.equal(extractCalls, 2, 'extração rodou duas vezes de verdade - execução at-least-once');
assert.equal(outbox.pendingRows().length, 1, 'mas só um evento foi commitado - efeito exactly-once');

Extração roda duas vezes (o worker não tem como saber que já tinha terminado antes de cair); o commit no outbox é o único lugar que sabe que aquela chave já tem resultado, então a segunda tentativa retorna o resultado existente em vez de criar um segundo evento. Uma revisão, não duas.

DLQ, quarentena e reprocesso auditável

Nem todo erro merece retry. Um documento com schema inválido não vai passar na segunda tentativa só porque esperou trezentos milissegundos - é uma falha permanente, e retry-policy.mjs a manda direto para a DLQ na primeira tentativa, sem queimar maxAttempts em algo que não vai mudar. O motivo gravado junto do job na DLQ é um código classificado (permanent_error, max_attempts_exceeded), nunca a mensagem crua do erro - a mensagem de um parser pode conter um trecho do documento, e um painel de operação de fila não é lugar para isso vazar.

Reprocessar um job da DLQ é um comando, não uma retentativa automática: exige operatorId, cria um job novo com operationVersion + 1 (nunca ressuscita o job morto no lugar) e grava uma entrada de auditoria ligando o job antigo, o novo e quem decidiu. Isso é deliberado: se um documento precisa ser tentado de novo depois de uma correção manual, essa decisão tem nome e hora, do mesmo jeito que uma aprovação de revisão tem no capítulo 3.

Cancelamento é um terceiro balde, separado da DLQ. Um job cujo deadlineAt já passou é cancelado no momento em que alguém tenta pegá-lo (leaseNext), e cancelamento não entra no mapa de DLQ - não existe caminho de reprocessFromDlq para um job cancelado. Se um documento cancelado genuinamente precisar ser refeito, isso é uma decisão humana nova, com enqueue() explícito e versão nova, não uma ressurreição automática escondida atrás de um retry.

Fila local vs. workflow durável: onde o Temporal entra, honestamente

O Temporal resolve um problema mais amplo do que fila e outbox: durabilidade de execução, não só de mensagem. Uma Workflow Execution no Temporal roda por tempo indefinido e, ao falhar, não recomeça do zero - ela retoma via Replay, reconstruindo seu estado a partir de um Event History gravado, comparando os comandos gerados de novo contra o que já foi registrado. Isso só funciona porque o código do Workflow é determinístico por contrato: dado o mesmo Event History, ele tem que gerar os mesmos comandos toda vez que for reexecutado. Qualquer coisa não determinística - uma chamada de rede, um Date.now(), e sobretudo uma chamada de LLM, cuja resposta pode variar entre execuções mesmo com o mesmo prompt - precisa viver dentro de uma Activity, que o Temporal trata como uma caixa preta re-executável e faz o replay pular, não reexecutar.

A fila com outbox deste capítulo não tenta ser isso. Ela dura o efeito de um passo (o resultado mais o evento), não a execução inteira de um pipeline de múltiplos passos com estado de longa duração entre eles. Se o RelayOps um dia precisar de um workflow que sobrevive semanas, com passos condicionais dependentes do conteúdo do documento e retomada automática de onde parou, esse é exatamente o caso de uso que justificaria adotar um motor como o Temporal - mas essa adoção não foi feita, testada ou medida nesta sessão. O que existe aqui é a leitura da documentação oficial e uma comparação conceitual, não uma implementação.

Quatro falhas

Falha 1 - retry infinito

Sintoma: um job nunca sai da fila; o log mostra a mesma chave sendo tentada centenas de vezes. Causa: um retry sem teto de tentativas, geralmente porque alguém tratou "falha transitória" como "sempre vale tentar de novo" sem perguntar quantas vezes. Resposta: retry-policy.mjs tem exatamente três saídas (retry, dead_letter, cancel) e a saída retry só existe enquanto attempt < maxAttempts. O teste crash-recovery.test.mjs prova isso sob falha transitória permanente: três tentativas, depois DLQ, nunca uma quarta.

Falha 2 - LLM dentro de replay determinístico sem activity

Sintoma (em um sistema Temporal real, não implementado aqui): o Workflow produz comandos diferentes em execuções de replay do mesmo Event History, e o motor rejeita o replay com um erro de não-determinismo. Causa: colocar a chamada ao modelo diretamente no corpo do Workflow em vez de dentro de uma Activity - a resposta do modelo pode variar, e o Workflow precisa ser puro em relação ao seu próprio histórico. Resposta: a regra, direto da documentação oficial do Temporal, é que qualquer efeito colateral ou chamada não determinística mora em uma Activity. Como este capítulo não roda Temporal, a falha é documentada como risco de design, não reproduzida em um cluster real - fingir uma reprodução aqui seria inventar evidência.

Falha 3 - dual write banco/broker sem recuperação

Sintoma: o resultado existe no banco, mas ninguém foi notificado (ou o inverso: alguém foi notificado sobre uma transação que fez rollback). Causa: gravar no banco e publicar no broker como duas chamadas separadas, sem transação compartilhada. crash-recovery.test.mjs reproduz isso com uma função naiveDualWrite deliberadamente simples:

function naiveDualWrite(db, broker, key, payload, crashInjector) {
  db.set(key, payload); // "commit no banco" - nenhuma linha de outbox, nenhum rastro durável
  crashInjector('after_db_write_before_publish');
  broker.publish(payload); // nunca alcançado se a queda cair acima
}

O teste prova exatamente o que a AWS descreve como motivação do padrão: db.has(key) é verdadeiro, broker.published.length é zero. O evento sumiu, e nada no sistema sabe que deveria existir um. Resposta: outbox.commitResultWithEvent() grava as duas coisas juntas; uma falha no meio não deixa nenhuma das duas visível para quem chama de novo, e um sucesso deixa uma linha de outbox pendente que o relay eventualmente publica - mesmo que o processo original já tenha morrido.

Falha 4 - idempotência global que mistura tenants

Sintoma: o tenant B vê (ou sobrescreve) o resultado de um documento do tenant A porque os dois compartilham o mesmo documentId. Causa: uma chave de idempotência construída só a partir de documentId, sem o tenant como parte da chave. Resposta: buildIdempotencyKey exige tenantId válido antes de montar qualquer coisa - não existe um caminho de código que produza uma chave sem tenant. O teste correspondente cria dois tenants com o mesmo documentId e a mesma operationVersion e prova que as chaves, e os resultados armazenados sob elas, nunca colidem.

O que os testes provam e o que não provam

Os 15 testes (node --test examples/*.test.mjs, 100% verde) provam dedupe de chave e payload, isolamento entre tenants, o cenário de abertura fim-a-fim, republicação de relay absorvida pelo consumidor, o anti-padrão de dual write, DLQ com motivo redigido, teto de retries, cancelamento por deadline como beco sem saída da DLQ, e reprocesso auditado. Não provam semântica de um broker real (SQS, Kafka, RabbitMQ têm garantias e configurações próprias, algumas mais fortes que "at-least-once" sob condições específicas), atomicidade de transação PostgreSQL sob crash de processo real, durabilidade de disco depois de perda de energia, ou corrida genuína entre workers concorrentes - o simulador é single-thread e síncrono, então leaseNext() nunca compete de verdade consigo mesmo. Também não provam nada sobre um modelo real: extract() é uma função sintética fixa em todo teste.

O script examples/scripts/synthetic-metrics.mjs roda 12 documentos sintéticos e separa três números por documento: tempo de espera na fila (queueWaitMs, a única métrica que reflete lógica real de controle sob esta carga sintética), tempo de inferência (inferenceMs, constante fixa de 40ms, não uma latência medida de modelo) e tempo de espera por revisão humana (reviewWaitMs, constante fixa de 90ms, não comportamento medido de revisor). A profundidade da fila é amostrada por tick e varia de 1 a 7 no ensaio, com pico no meio do lote de doze documentos - evidência do formato da carga sintética, não uma capacidade de produção.

Custo, segurança e reversibilidade

Custo: cada retry queima uma chamada adicional (de extração, e potencialmente de modelo); um teto de tentativas não é só sobre travar loops, é sobre limitar quanto um documento problemático pode gastar antes de virar decisão humana. Segurança: o motivo gravado na DLQ é sempre um código curto, nunca o texto do erro ou do documento - um painel de operação de fila não deveria ser um vetor de vazamento de PII. Reversibilidade: cancelamento é terminal e não tem caminho de volta automático; reprocesso de DLQ cria um job novo e versionado, nunca sobrescreve o antigo, então o histórico de decisões (inclusive as erradas) permanece auditável. A lacuna real, registrada sem retoque em examples/pipeline-runbook.md: não há limite de taxa por tenant no reprocesso de DLQ nesta implementação - um operador (ou uma automação de operador) mal configurado poderia reprocessar o mesmo documento morto repetidamente sem que o sistema o impeça.

Outra lacuna que vale registrar em vez de esconder: outbox.mjs nunca remove uma linha já publicada - ela fica marcada published, mas continua ocupando memória (ou, em uma versão com banco, uma tabela) indefinidamente. Isso é aceitável para os 15 testes deste capítulo, que rodam em milissegundos e nunca chegam perto de um volume que importe, mas é exatamente o tipo de decisão que precisa de uma política explícita de retenção antes de qualquer coisa próxima de produção - por quanto tempo uma linha publicada precisa sobreviver para uma auditoria retroativa, e quem decide quando arquivá-la ou apagá-la. Nenhuma dessas duas perguntas tem resposta neste capítulo; ambas ficam registradas como trabalho futuro, não como comportamento implícito do código.

Checklist antes de declarar um pipeline durável

• A chave de idempotência inclui tenant, documento e versão da operação - nunca documento sozinho.
• Payload divergente sob a mesma chave é rejeitado, não reaproveitado silenciosamente, em pelo menos dois pontos (entrada e persistência).
• Todo job tem lease, heartbeat e deadline - e retry e deadline são limites independentes, não um substituindo o outro.
• Toda classificação de erro produz retry, dead_letter ou cancel - nunca um estado indefinido que alguém precisa adivinhar depois.
• Resultado e evento de notificação são persistidos juntos, nunca como duas chamadas separadas sem transação compartilhada.
• DLQ grava motivo classificado e redigido; reprocesso exige identidade de operador e cria versão nova.
• Cancelamento é terminal e distinto de DLQ; nada o transforma automaticamente em um novo job.
• Métricas de fila (idade do job, profundidade, tempo até revisão) separam tempo de espera, tempo de inferência e tempo de revisão humana - nunca um número único que os esconde.

Exercícios

Básico - deduplicar redelivery. Critério verificável: dado um evento já processado (mesmo eventId), uma segunda chamada a consumer.handle(event) retorna { applied: false, reason: 'duplicate_event' } e consumer.appliedEvents().length permanece 1. Solução comentada: createDedupingConsumer() em examples/src/outbox.mjs guarda um Set de eventIds vistos, independente do estado do outbox - é isso que garante que mesmo uma republicação do relay (não só uma redelivery de fila) seja absorvida no ponto certo. Ver o teste 'consumer dedupes redelivered events by eventId' em examples/idempotency.test.mjs, executado de fato (não apenas descrito) como parte de node --test examples/*.test.mjs.

Intermediário - injetar crash após outbox persistida e provar retomada. Critério verificável: injetar CrashSimulated no estágio after_commit_before_ack, confirmar que o job continua com status leased e que existe exatamente uma linha pendente no outbox, avançar o relógio além do lease, chamar processOnce() de novo e confirmar outcome === 'acked' com deduped === true. Solução comentada: o teste 'intermediate exercise: inject a crash right after the outbox commit and prove resumption end to end' em examples/crash-recovery.test.mjs faz exatamente essa sequência e termina publicando o evento e confirmando que o consumidor aplicou exatamente uma vez - comando real, node --test examples/crash-recovery.test.mjs, não trecho hipotético.

Avançado - contrastar simulador com integração transacional PostgreSQL/broker. Critério verificável (não executado nesta sessão - protocolo, não resultado): substituir os Maps de outbox.mjs por duas tabelas PostgreSQL escritas dentro de uma única transação por commitResultWithEvent, com idempotency_key como UNIQUE constraint; matar o processo (kill -9) entre os INSERTs e o COMMIT em um teste real e confirmar rollback completo; substituir a chamada direta de relayPublishOnce por um broker real com SELECT ... FOR UPDATE SKIP LOCKED para impedir que duas instâncias do relay disputem a mesma linha - exatamente o cenário de concorrência que o simulador deste capítulo, single-thread, não consegue exercitar. examples/pipeline-runbook.md lista, além disso, falhas que essa integração ainda não cobriria: partição de rede durante o commit (o chamador não pode tratar um timeout como "não aconteceu" e reprocessar às cegas) e perda de mensagem por má configuração do lado do broker.

Glossário

• At-least-once delivery: garantia de que uma mensagem/job nunca é descartado silenciosamente, ao custo de poder ser entregue mais de uma vez.
• Idempotência: aplicar uma operação duas vezes produz o mesmo efeito observável de aplicá-la uma vez.
• Lease: posse temporária e renovável de um job por um worker, com expiração explícita.
• Fencing token: número monotônico por lease que invalida ações de um worker cuja posse já expirou.
• Outbox transacional: gravar um resultado e o evento que o anuncia na mesma transação, para que um relay publique depois sem risco de perder o evento ou publicar um que nunca deveria ter existido.
• DLQ (dead-letter queue): destino de jobs que esgotaram tentativas ou falharam de forma permanente, à espera de decisão humana.
• Replay determinístico: em um motor como o Temporal, reconstrução do estado de uma execução a partir do histórico gravado, que só funciona se o código reexecutado gerar sempre os mesmos comandos.

Ponte para o capítulo 5

Este capítulo garantiu que um efeito aconteça uma única vez mesmo sob crash - mas não decidiu nada sobre o que um agente deveria lembrar entre execuções diferentes, nem sobre quando uma resposta anterior do modelo deveria influenciar uma decisão futura sem virar um RAG por conveniência. O capítulo 5 parte exatamente daí: que proveniência uma memória de longo prazo carrega, e quem decide se ela pode ser usada quando o orçamento de uma tarefa já passou do previsto.