A perda de energia durante uma ação auditada de um agente deixa resultados desconhecidos

Uma perda de energia durante uma ação auditada de um agente não cria uma única falha. Ela cria um problema de evidências. O agente, o gateway local, o sistema operacional, a rede e o serviço remoto podem parar em pontos diferentes. Se você resumir essa confusão como «falha» porque o agente não recebeu uma resposta, cedo ou tarde repetirá uma ação que já aconteceu.

Esse erro é fácil de cometer porque os registros parecem contar uma história. O investigador vê uma ação aprovada, uma solicitação de saída e, depois, uma lacuna. A lacuna parece uma conclusão. Não é. Ela é um intervalo em que vários resultados materialmente diferentes continuam possíveis, e a resposta correta depende de qual sistema é responsável pelo fato que você precisa descobrir.

É aqui que uma trilha de auditoria mostra seu valor. Ela deve preservar o que o sistema local sabe, provar que os registros retidos não foram editados silenciosamente e tornar a incerteza visível, em vez de escondê-la. Ela não pode transformar uma resposta perdida em prova de que uma gravação no banco de dados, um pagamento, uma implantação ou um comando remoto não ocorreu.

Um timeout é uma lacuna de evidências, não uma falha confirmada

Um timeout informa que um participante não observou uma resposta utilizável antes do prazo. Ele não informa se o destino recebeu a solicitação, se começou o trabalho, se confirmou o trabalho ou se a resposta desapareceu no caminho de volta.

Mantenha estes resultados separados nas notas do incidente e em qualquer interface que apresente ações do agente:

• Falha confirmada: o destino ou executor local retornou evidência durável de que rejeitou ou desfez a operação solicitada.
• Sucesso confirmado: o sistema responsável pelo estado alterado retornou um recibo, e uma leitura posterior confirma o estado esperado.
• Resultado desconhecido: a ação pode ter acontecido, mas as evidências disponíveis não permitem estabelecer se aconteceu ou não.
• Não tentada: o gateway negou a ação antes de entregá-la a um executor ou transporte.

«Desconhecido» não é uma forma cautelosa de dizer «provavelmente falhou». É um estado operacional com um procedimento diferente. Você pausa as tentativas automáticas, preserva as evidências, consulta o sistema responsável e só então decide se uma ação compensatória ou uma nova tentativa é segura.

As pessoas costumam acrescentar cedo demais um quarto rótulo, «parcialmente concluída». Use-o apenas quando puder indicar a suboperação concluída e a suboperação incompleta. Um pipeline de implantação que criou um artefato, mas nunca o promoveu, tem um resultado parcial se os dois fatos forem verificados. Uma solicitação que desapareceu depois que o cliente escreveu bytes em um socket tem resultado desconhecido, mesmo que a solicitação parecesse simples.

A RFC 9110 faz a mesma distinção em termos de protocolo. Ela permite a repetição automática de métodos idempotentes depois de uma falha de comunicação, porque repetir a operação pretendida produz o mesmo efeito pretendido. Ela desaconselha repetir automaticamente uma solicitação não idempotente, a menos que o cliente consiga estabelecer que a solicitação original não foi aplicada ou saiba que a aplicação torna as repetições seguras. Essa é uma regra semântica, não um truque de transporte.

Um gateway de ações de agentes deve informar os fatos locais com precisão. «Solicitação enviada; conclusão não observada» é útil. «Ação falhou» é uma afirmação que o processo local talvez não tenha autoridade para fazer.

A perda de energia divide uma ação em limites de durabilidade

Uma ação pode atravessar vários limites antes que alguém veja um resultado final. Anote-os antes dos testes, porque um teste que derruba apenas um processo pode produzir uma confiança enganosa.

Uma ação HTTP típica tem pelo menos estes limites:

1. O gateway aceita uma intenção autorizada e a registra localmente.
2. O gateway monta e começa a transmitir a solicitação autenticada.
3. O serviço remoto recebe dados suficientes para começar a processá-la.
4. O serviço remoto confirma seu efeito colateral e cria um recibo.
5. O gateway recebe a resposta e registra o resultado observado.

Uma ação SSH segue um caminho semelhante, mas o host remoto pode iniciar um comando antes que o cliente local saiba seu status de saída. O host também pode criar um processo que sobreviva à sessão. Uma conexão TCP ou SSH bem-sucedida diz muito pouco sobre o ponto em que um comando parou.

As gravações locais têm seus próprios limites. Um processo pode acrescentar um evento de auditoria, o sistema operacional pode aceitar esse acréscimo em cache, o sistema de arquivos pode ordenar metadados e dados, e o armazenamento pode fazer os bytes sobreviverem à perda de energia. Esses eventos não são equivalentes.

A especificação POSIX de fsync() diz que a chamada solicita a transferência dos dados enfileirados de um arquivo aberto para o dispositivo de armazenamento e só retorna quando a operação termina ou informa um erro. A justificativa também alerta que a garantia real depende da implementação e da configuração do armazenamento. Essa ressalva é importante: uma aplicação não pode inferir segurança contra perda de energia apenas porque uma chamada de gravação retornou com sucesso.

Para a investigação, atribua a cada registro uma classe de evidência, em vez de tratar todos os horários como igualmente duráveis:

Essa tabela é deliberadamente rigorosa. Uma linha de registro de processo que diz «enviando solicitação» é evidência de despacho. Não é evidência de entrega. Um corpo de resposta mantido na memória é evidência de observação. Ele só se torna evidência local durável quando o caminho de persistência sobrevive ao modelo de falha que você afirma testar.

Dê uma identidade de operação a cada efeito colateral antes de testar falhas

Um investigador não consegue reconciliar uma ação interrompida se o sistema remoto não tiver uma forma estável de identificá-la. Adicione uma identidade de operação antes de escrever um teste de caos, não depois que a primeira duplicata aparecer em produção.

Use dois identificadores quando puder:

• Um ID de ação gerado localmente, que identifica a tentativa única do gateway.
• Um ID de operação reconhecido pelo destino, uma chave de idempotência, um token de solicitação, um ID de implantação ou uma referência de transação.

Eles podem conter o mesmo valor aleatório, mas não presuma que significam a mesma coisa. Seu ID de ação identifica um registro de auditoria local. O identificador remoto só se torna útil quando o destino o armazena junto com o efeito colateral e oferece uma forma de consultar o estado resultante.

Para uma API que aceita chaves de idempotência, deixe a identidade explícita na solicitação e registre um resumo do conteúdo relevante. O resumo permite detectar quando um operador tenta reutilizar acidentalmente uma chave antiga com uma solicitação alterada.

POST /v1/releases HTTP/1.1
Host: deploy.example.internal
Idempotency-Key: 8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1
Content-Type: application/json

{
  "operation_id": "8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1",
  "service": "catalog",
  "artifact": "sha256:3c1f...",
  "environment": "production"
}

Não registre o cabeçalho de autorização, o bearer token nem um corpo completo que possa conter segredos. Registre o método, a identidade do destino, os metadados seguros da solicitação, o ID de ação, o ID de operação e o resumo do conteúdo. Você precisa de evidências suficientes para comparar tentativas sem criar um segundo vazamento de credenciais no sistema de auditoria.

Um registro de intenção pode ter esta aparência:

{
  "event": "intent_accepted",
  "action_id": "act_01JX8F3Z6Z",
  "operation_id": "8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1",
  "channel": "http",
  "destination": "deploy.example.internal",
  "method": "POST",
  "path": "/v1/releases",
  "payload_sha256": "3c1f...",
  "authorization": "approved_for_session"
}

Esse registro evita um erro comum de investigação: alguém compara uma nova tentativa com a primeira ação usando apenas o horário e o endpoint, ignora um artefato ou uma conta alterados e declara que as duas operações são equivalentes.

No SSH, coloque o ID de operação onde o host remoto possa preservá-lo. Um comando shell pode incluí-lo nos registros estruturados, um script de implantação pode gravá-lo em um registro de release ou um wrapper remoto pode rejeitar um ID duplicado. Não dependa da transcrição do cliente SSH local como sua única prova.

ssh [email protected] \
  '/usr/local/bin/release --operation-id 8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1 --artifact sha256:3c1f...'

Se esse comando iniciar um worker em segundo plano, faça o worker persistir o ID de operação antes de alterar qualquer coisa. Caso contrário, uma desconexão deixará um host que talvez ainda esteja trabalhando e nenhuma forma confiável de encontrar esse trabalho.

Simule interrupções nos limites que mudam sua decisão

Um bom teste de falha encerra o processo em pontos que levam a decisões diferentes por parte do investigador. Terminar aleatoriamente um cliente em um loop encontra bugs, mas não ensina ninguém a interpretar o registro.

Monte um destino de teste que possa pausar em fases controladas e responder a uma consulta de reconciliação por ID de operação. Ele não precisa ser sofisticado. Precisa expor a diferença entre solicitação recebida, efeito colateral confirmado e resposta enviada.

Comece com cinco casos:

1. Falha antes da persistência da intenção. A ação deve estar ausente da trilha local durável e do destino. Se o destino mudou, a ordem das operações está errada ou outro componente emitiu a ação.
2. Falha depois da persistência da intenção, mas antes do despacho. A trilha de auditoria deve mostrar uma ação aceita sem registro de despacho. Isso só deve ser classificado como não tentado se o gateway puder provar que nunca entregou a ação a um transporte ou executor.
3. Falha durante a transmissão da solicitação. O destino pode não ver nada, receber uma solicitação parcial ou receber a solicitação completa. Classifique como desconhecido, a menos que o destino forneça uma rejeição ou um resultado de consulta definitivo.
4. Falha depois da confirmação remota, mas antes da persistência da conclusão local. O destino deve mostrar a operação como concluída, enquanto a trilha local não tem um evento de conclusão. Esse é o teste que revela uma lógica de repetição perigosa.
5. Falha depois da persistência da conclusão local, mas antes que o agente receba a resposta. A trilha de auditoria local contém a resposta, embora o agente pense que houve um timeout. Uma nova sessão do agente deve consultar o registro da ação, em vez de emitir cegamente uma segunda operação.

Um harness local pode coordenar o gateway e um serviço de teste usando arquivos de pausa nomeados. A implementação exata varia, mas o contrato do teste não deve variar. O harness precisa informar qual limite alcançou antes da interrupção e preservar o estado do destino para reconciliação.

# Terminal 1: start the test destination with controlled pauses.
./test-api --pause-after=commit --state-file ./tmp/remote-state.json

# Terminal 2: run one authorized action with a known operation ID.
./gateway-test invoke \
  --operation-id 8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1 \
  --pause-file ./tmp/client-dispatch.pause

# When the destination reports "committed", terminate the local process.
kill -9 "$(pgrep -f 'gateway-test invoke')"

# Terminal 3: inspect the destination without issuing another mutation.
./test-api lookup 8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1

kill -9 testa a falha de um processo. Ele não testa o comportamento do armazenamento durante um corte brusco de energia e não cancela uma ação que o serviço remoto já aceitou. Essa limitação é útil quando você está aprendendo a classificar resultados. Ela obriga a equipe a parar de tratar a morte do solicitante como prova sobre o destinatário.

Para testar uma perda real de energia, use uma máquina descartável ou um ambiente virtualizado em que seja possível reproduzir desligamentos abruptos com segurança. Não retire a energia de uma estação de trabalho que contenha a única cópia de um cofre de produção, material de auditoria ou uma árvore de trabalho. Salve a compilação exata, o modo de armazenamento, as entradas de teste e a fonte de tempo de cada execução. Um resultado de teste sem esse contexto é apenas uma anedota.

Uma trilha de auditoria deve declarar o que sabe e preservar o que não sabe

Um bom registro de auditoria se parece com um conjunto de afirmações com escopo claro. Ele não finge conter uma verdade onisciente sobre sistemas que não consegue observar.

Para uma ação interrompida, registre eventos separados em vez de sobrescrever um único campo de status mutável. Uma sequência somente de acréscimo pode representar a verdade sem inventar uma resposta final:

intent_accepted     action=act_01JX8F3Z6Z op=8b4d... principal=agent-process
transport_started   action=act_01JX8F3Z6Z channel=http
outcome_unobserved  action=act_01JX8F3Z6Z reason=local-process-terminated
reconciled_success  action=act_01JX8F3Z6Z receipt=rel_4921 source=remote-api

A terceira linha não deve dizer remote_failed. Ela apenas diz que o gateway não conseguiu observar um resultado terminal. A quarta linha acrescenta uma afirmação posterior da fonte responsável pelo estado do release.

Essa distinção também torna a evidência contra adulteração mais útil. Uma cadeia de hash pode revelar alterações no material de auditoria retido, mas não pode recriar um evento que nunca chegou ao armazenamento durável. Se uma máquina perde energia entre uma chamada de saída e um acréscimo ao registro, uma cadeia intacta pode terminar de forma limpa antes do resultado da ação. Isso não significa necessariamente que a cadeia esteja quebrada. É uma lacuna que precisa de reconciliação.

Os projetos do Sallyport Sessions e Activity são derivados de um único registro de auditoria criptografado, encadeado por hash e sem acesso direto para escrita, e sp audit verify verifica essa cadeia offline sobre o texto cifrado. Isso oferece ao investigador uma forma sólida de verificar se o histórico local retido foi alterado, deixando o resultado remoto para as evidências remotas quando necessário.

Mantenha as evidências de autorização separadas das evidências de resultado. Uma aprovação mostra que uma pessoa ou um controle configurado permitiu que uma ação prosseguisse. Ela não mostra que a ação foi concluída. Misturar essas afirmações é como uma alteração de produção aprovada, mas interrompida, acaba sendo relatada falsamente como concluída.

O mesmo alerta vale para os horários. Horários de relógio ajudam os investigadores a correlacionar sistemas, mas não estabelecem uma ordem global quando as máquinas divergem ou buffers atrasam as gravações. Se a ordem for importante, registre números de sequência em cada diário, preserve IDs de recibos remotos e capture os horários do próprio serviço durante a reconciliação.

Chamadas de rede precisam de reconciliação remota, não de otimismo

Quando uma chamada HTTP perde sua resposta, o destino costuma ser a autoridade sobre a mudança do estado solicitado. Consulte-o antes de repetir a chamada e torne a consulta específica o suficiente para distinguir essa operação de trabalhos semelhantes.

A ordem mais segura para a reconciliação é:

1. Consulte o ID de operação ou a chave de idempotência no destino.
2. Se o destino retornar uma operação concluída, compare os IDs dos recursos e o resumo do conteúdo com a intenção original.
3. Se retornar uma rejeição registrada, preserve essa resposta como evidência de falha.
4. Se não houver registro, verifique se a API documenta processamento atrasado, filas assíncronas ou criação eventual do registro antes de emitir uma nova tentativa.
5. Repita apenas quando a semântica do endpoint e as evidências tornarem a repetição segura.

Não confunda uma solicitação GET com uma verificação inofensiva apenas porque ela usa um método seguro. Algumas APIs escondem trabalho atrás de um endpoint de leitura, e alguns caches de resposta ficam atrasados em relação ao caminho de gravação. Verifique o contrato do provedor e, quando possível, recupere o recurso específico criado ou o registro da operação, em vez de pesquisar uma lista ampla pelo horário.

Os rótulos dos métodos HTTP ajudam, mas não resolvem o comportamento da aplicação. Uma solicitação PUT pode ser idempotente na camada HTTP, enquanto o servidor envia e-mails duplicados, cobra uso ou aciona um hook de implantação a cada recebimento. A RFC 9110 observa explicitamente que a idempotência se aplica ao efeito solicitado, enquanto o servidor ainda pode manter registros separados ou produzir outros efeitos colaterais. Por isso, a identidade de operação documentada pelo responsável pela API importa mais do que um verbo em uma biblioteca cliente.

Uma recomendação popular, mas ruim, é «repita todo timeout duas vezes». Ela parece prática porque muitos timeouts são transitórios. Porém, pode transformar um problema transitório de transporte em movimentação financeira duplicada, criação duplicada de contas ou duas releases de produção quando o endpoint não pode ser repetido com segurança. Uma política de repetição deve indicar o tipo de operação, o mecanismo de idempotência, o atraso máximo e as evidências que permitem a repetição.

Para um serviço remoto que não oferece consulta nem suporte à idempotência, a resposta honesta pode ser que você não consegue resolver o resultado automaticamente. Crie um processo compensatório em torno dessa limitação, como uma fila de revisão humana com a impressão digital exata da solicitação e uma conta somente leitura capaz de inspecionar o estado afetado.

Comandos SSH exigem provas do host remoto

Uma sessão SSH interrompida deixa mais ambiguidade do que muitas chamadas de API, porque o comando pode ser executado do outro lado depois que o cliente desaparece. Um status de saída perdido não significa que o comando falhou. Significa que a observação está ausente.

Evite uma única linha shell grande que faça várias alterações sem pontos de verificação. Divida o trabalho remoto em operações com seus próprios IDs e estado durável. Um wrapper de implantação, por exemplo, pode registrar received, validated, applied e completed para um ID de operação e depois expor um comando de status somente leitura.

/usr/local/bin/release-status \
  --operation-id 8b4dbdb6-61e1-49ea-a5b5-9ae225eb2af1

O wrapper deve gravar seu status antes de iniciar uma ação que não possa ser repetida, não depois. Se ele alocar um recurso de nuvem, publicar um pacote ou mudar o tráfego, deve preservar o recibo do provedor com o mesmo ID de operação. Se não puder fazer isso, coloque a operação em uma fila remota que possa.

Desconfie de traps de limpeza do shell como evidência de recuperação. Um trap local não é executado depois de uma perda abrupta de energia. Um trap remoto pode não ser executado depois de uma eliminação forçada e pode ser executado enquanto um processo filho continua. A lógica de limpeza pode reduzir a desordem, mas não prova o estado final.

Use um marcador remoto apenas quando ele tiver uma relação significativa com o efeito colateral. Uma linha acrescentada a /tmp/action-done não prova que uma migração de banco de dados foi confirmada. Uma entrada na tabela de migrações escrita na mesma transação é uma evidência melhor. Um registro de implantação criado pelo controlador de implantação é melhor ainda.

O Sallyport encaminha SSH por meio do auxiliar stateless sp-ssh incluído, mas a mesma regra se aplica: o registro local da ação pode estabelecer o que o gateway tentou e observou. Apenas o host remoto, ou o sistema alterado pelo comando, pode resolver um resultado remoto não observado.

Conduza o investigador por uma release interrompida

Suponha que um agente solicite uma release de produção por meio de um endpoint HTTP. O gateway registra uma intenção autorizada com o ID de ação act_01JX8F3Z6Z, o ID de operação 8b4d..., o resumo do artefato 3c1f... e uma aprovação de sessão. Ele inicia a solicitação. O serviço de release confirma a release e atribui o recibo rel_4921. Antes que a resposta chegue ao gateway, o laptop perde energia.

Depois da reinicialização, a transcrição do agente informa que a chamada sofreu timeout. A trilha de auditoria local termina em transport_started. Alguém que trate essa linha como prova de falha envia a mesma release novamente, desta vez com um novo ID de operação. O serviço cria uma segunda release. Se o endpoint ativar imediatamente, a segunda solicitação pode ser apenas ruído. Se acionar uma migração irreversível, pode ser cara.

A investigação correta começa bloqueando a repetição automática de act_01JX8F3Z6Z. Verifique a cadeia de auditoria local. Registre o último evento retido, as evidências de encerramento do processo local, o destino, o resumo do conteúdo e o ID de operação. Depois, consulte o serviço de release por 8b4d....

Há três resultados úteis:

• O serviço retorna rel_4921 com o resumo do artefato 3c1f.... Classifique a ação original como sucesso confirmado após a reconciliação. A conclusão local ausente continua sendo uma lacuna de auditoria, não um motivo para repetir a release.
• O serviço retorna uma rejeição durável associada a 8b4d.... Classifique-a como falha confirmada. Preserve o motivo da rejeição antes de decidir se uma solicitação corrigida é adequada.
• O serviço não retorna nenhum registro. Verifique se ele coloca solicitações em fila antes de criar registros de operação e se o caminho de consulta tem atraso. Se não puder excluir trabalho atrasado, mantenha o resultado desconhecido e encaminhe o caso, em vez de fazer uma nova tentativa às cegas.

Observe o que não decide o caso: o timeout do agente, o encerramento do processo do gateway ou o fato de uma pessoa ter aprovado a ação. Esses fatos importam, mas nenhum deles é responsável pelo estado da release.

Este exemplo também revela um requisito de projeto. Se o destino não puder pesquisar por ID de operação, o gateway deve evitar ações não repetíveis sem supervisão nesse destino ou exigir um caminho de reconciliação humana. A qualidade da auditoria não compensa uma API que não oferece uma forma durável de identificar seus próprios efeitos colaterais.

As regras de repetição devem ser restritas o bastante para sobreviver a um dia ruim

Uma política de repetição deve dizer mais do que «repita em caso de erros de rede». Escreva-a como uma tabela de decisão que tanto quem implementa quanto quem responde a incidentes possa seguir.

Não permita que os agentes inventem um novo ID de operação durante a recuperação. Esse é um gerador sutil de duplicatas. Se uma repetição for válida, reutilize a mesma identidade reconhecida pelo destino e prove que o conteúdo da nova tentativa corresponde à intenção original. Se a mudança desejada tiver mudado, trata-se de uma nova ação que merece uma nova decisão de autorização.

Defina um estado terminal para ações não resolvidas. «Desconhecido, aguardando reconciliação» é melhor do que um job que tenta novamente para sempre porque ninguém escreveu a máquina de estados para admitir a incerteza. Dê a esse estado um responsável, um prazo e um caminho de escalonamento. Caso contrário, uma ação ambígua antiga se tornará uma surpresa quando alguém voltar a ela semanas depois, com registros remotos incompletos.

Preserve as evidências antes que os sistemas deixem de ter a resposta

A primeira hora depois de uma interrupção é quando os serviços remotos ainda têm rastros de solicitações, entradas de fila e o contexto recente dos operadores. Capture os fatos antes que a retenção de registros, a remoção de cache ou outra implantação os elimine.

Preserve o material de auditoria local em sua forma original e verifique-o antes de copiar trechos para um chamado. Registre o ID exato da ação, o ID da operação, o destino, o resumo do conteúdo, o registro de autorização, o último evento local e o horário da reinicialização local. Depois, colete o registro da operação remota, a revisão do recurso, o ID da solicitação do provedor e a fonte de tempo do serviço usada para chegar à resposta.

Não conserte o histórico adicionando um evento de conclusão falso. Acrescente um evento posterior de reconciliação que indique sua fonte e suas evidências. Os investigadores precisam ver o limite original, porque ele mostra o que o sistema sabia naquele momento.

A lição durável é desconfortável, mas simples: uma ação auditada pode estar bem autorizada, cuidadosamente registrada e ainda assim ter um resultado remoto desconhecido depois de uma perda de energia. Crie identidades de ação, recibos remotos e caminhos de reconciliação antes de permitir que um agente autônomo execute um trabalho que não possa acontecer com segurança duas vezes. Quando as luzes se apagam no momento errado, essas escolhas determinam se sua equipe investigará uma lacuna ou criará um segundo incidente.