O agente caiu depois da mudança. Você deve repetir?

Imagine uma ferramenta que corrige uma configuração. Ela recebe uma proposta revisada, verifica a versão do alvo e aplica a mudança. Antes de devolver sucesso, o processo termina. O cliente vê uma interrupção. O alvo talvez já tenha mudado. Uma linha de log dizendo que a chamada começou não permite escolher entre essas possibilidades.

Neste exercício, o alvo é apenas uma linha SQLite que representa um bucket sintético. A propriedade blockPublicAccess serve como estado didático; não é uma chamada ao S3. A proposta identifica a operação e a versão esperada. Um registro de intenção, chamado ledger, guarda o pedido revisado. Um recibo registra que aquele pedido produziu aquela versão do alvo.

Essa separação permite formular uma pergunta verificável: qual evidência liga esta operação a esta mudança? Ver a configuração desejada não responde quem a mudou. Encontrar um processo reiniciado não responde se o processo anterior concluiu. Uma mensagem de erro no cliente descreve a observação do cliente, e não necessariamente a realidade do destino.

Use Node.js 22.13 ou posterior, com node:sqlite disponível. O código-fonte da tag é a referência deste exercício; não presuma que a versão publicada no npm seja a mesma. A instalação de dependências não é necessária para executar este laboratório. Faça o clone em uma pasta nova, confira a tag e rode os testes antes de alterar qualquer cenário.

Escolha nomes de banco novos em cada repetição completa. Um banco reaproveitado preserva histórico, e esse histórico muda o resultado esperado. Preserve também a proposta original: gerar outra depois da mudança pode criar um digest diferente para o mesmo identificador e deve resultar em conflito, não em uma autorização implícita para executar novamente.

Os comandos com falha intencional estão separados dos comandos de inspeção. Em um script com set -e, capture explicitamente o código 86 para que a interrupção esperada não encerre sua investigação. O teste de incerteza retorna 2, outro resultado previsto. Esses códigos fazem parte da evidência; não devem desaparecer em um || true indiscriminado.

Crie o banco e exporte a proposta. O comando run com --approve simula uma revisão explícita e grava a intenção. O ponto after-target encerra o processo depois do commit que atualiza o alvo e escreve o recibo, antes de marcar a operação como concluída. Não é uma exceção capturada dentro de uma única função: o CLI termina e os comandos seguintes abrem o banco em outros processos.

Depois da queda, inspecione três coisas juntas: o status da operação, a versão do alvo e a existência do recibo. Na execução de 27 de outubro, a operação estava pending, o alvo estava na versão 2 com blockPublicAccess: true, e havia um único recibo associado ao digest da proposta. Essa combinação demonstra por que repetir só porque o ledger está pendente seria uma decisão mal informada.

O comando recover consulta a operação, o recibo e o estado atual. Neste caso, muda a classificação para reconciled e registra a decisão no histórico. Ele não altera o alvo. A repetição da proposta original também retorna reconciled, com retryable: false. Na inspeção final, a versão permanece 2 e a quantidade de recibos permanece 1.

Esses são os invariantes que vale conferir. O teste não consiste apenas em procurar a palavra sucesso na saída. Compare o efeito observável antes e depois da recuperação. Compare também antes e depois da repetição. Se a versão tivesse aumentado de novo, um status aparentemente correto esconderia uma segunda execução.

O recibo é evidência histórica, não um selo permanente de saúde. Se o alvo sofrer uma mudança posterior, o histórico da operação anterior pode continuar válido enquanto o estado atual diverge. A implementação expõe driftAfterReceipt para distinguir essas perguntas. Restaurar o estado desejado, quando necessário, exige uma nova decisão revisada sobre o estado atual.

Agora use outro banco. Interrompa a execução em after-intent, antes de aplicar o efeito. Em seguida, use o comando didático drift para mudar o alvo por outro caminho. Ao recuperar, a propriedade desejada estará verdadeira e a versão será 2, assim como no primeiro experimento. A diferença decisiva é a ausência de recibo.

O resultado observado é uncertain, retryable: false, com código de saída 2. Reenviar a proposta original mantém essa classificação e não modifica novamente o alvo. O sistema não deduz autoria a partir de coincidência de valores. Esse comportamento troca disponibilidade automática por uma decisão que pode ser investigada.

Não apague a operação para destravar a fila. Isso elimina a memória usada para reconhecer a duplicata. Preserve o banco, a proposta e os resultados; investigue a mudança e defina o próximo passo como uma nova decisão. O laboratório não oferece um botão mágico de resolução administrativa, nem deve sugerir que editar o ledger manualmente seja um procedimento seguro.

A implementação persiste a intenção revisada em uma transação. Em outra, compara a versão esperada e grava o alvo junto com o recibo. Em uma terceira, marca a conclusão no ledger. O recibo e a mudança são atômicos entre si; a execução completa não é uma transação única. Essa escolha cria deliberadamente a janela que acabamos de testar.

BEGIN IMMEDIATE serializa os escritores no arquivo local, com espera de contenção limitada. O armazenamento usa WAL e synchronous=FULL. Essas escolhas dão semântica transacional ao exercício, mas os testes de encerramento de processo não equivalem a testes de energia, disco, corrupção ou sistema de arquivos de rede. O custo da serialização também importa: um único arquivo local não representa escalabilidade distribuída.

A suíte cobre outras fronteiras: queda antes do commit do alvo, antes do commit de conclusão e depois da conclusão; processos concorrentes; identificadores repetidos com payload diferente; propostas sem revisão e alterações de estado. Os 22 testes que passaram são verificações dessas propriedades no laboratório, não uma porcentagem de disponibilidade ou uma taxa de sucesso de um agente em produção.

Em uma integração real, gravar intenção em um banco e chamar uma API remota são operações em sistemas diferentes. O commit local não engloba a API. O laboratório coloca alvo e recibo juntos justamente para tornar a evidência inspecionável; transportar o desenho para a nuvem exige reavaliar essa fronteira.

A AWS Builders' Library explica o valor de um identificador explícito fornecido pelo cliente para reconhecer a intenção de repetição. Confira o contrato de idempotência da operação concreta: escopo, validade do token, comportamento com parâmetros diferentes e resposta em chamadas repetidas. Não derive uma garantia universal porque outro serviço aceita um token.

Para cada ferramenta mutável, registre quais evidências remotas estão disponíveis, quanto tempo permanecem consultáveis e quem resolve um resultado inconclusivo. Quando o destino não oferece uma prova suficiente, mantenha um estado de incerteza visível. Adicionar uma fila, um framework de agentes ou um servidor MCP não fecha sozinho o intervalo entre efeito e confirmação.

Também separe a autorização atual da evidência histórica. --approve neste laboratório é apenas uma simulação local de revisão. Um serviço real precisa verificar identidade, escopo e validade antes da mutação; uma aprovação revogada não deve virar permissão de nova execução só porque existe um registro antigo. Uma consulta de recuperação e uma tentativa de mutação exigem decisões distintas.

Para compartilhar um caso reproduzível, leve a versão do código, o estado inicial sintético, a proposta, o ponto de interrupção, os códigos de saída e as inspeções antes e depois. Uma captura de terminal ajuda a comunicar; os arquivos e comandos permitem verificar. Remova credenciais e dados reais antes de abrir uma issue.

A evidência pública associada a este artigo contém os resultados dos dois cenários. A proposta é abrir discussão sobre um contrato concreto: qual observação permitiria reconciliar, qual permitiria tentar novamente e qual exige investigação? Uma contribuição pequena, como acrescentar um caso de falha com resultado esperado, pode ser mais útil do que adicionar mais uma ferramenta ao catálogo.

Se quiser experimentar, execute os dois cenários no repositório e descreva qual fronteira de falha você testaria em seguida. Para trazer isso à sua arquitetura AWS, comece por uma única operação mutável e documente seu contrato de idempotência e recuperação. A partir daí, o teste deixa de ser uma demonstração genérica de agente e passa a ser uma propriedade que a equipe consegue revisar.