Una pérdida de energía durante una acción auditada de un agente deja resultados desconocidos

Una pérdida de energía durante una acción auditada del agente no crea un único fallo. Crea un problema de pruebas. El agente, la pasarela local, el sistema operativo, la red y el servicio remoto pueden detenerse en puntos distintos. Si reduces todo ese desorden a «fallo» porque el agente no recibió respuesta, tarde o temprano volverás a intentar una acción que ya se había ejecutado.

Es fácil cometer ese error porque los registros parecen contar una historia. Un investigador ve una acción aprobada, una solicitud saliente y después un vacío. El vacío parece una conclusión. No lo es. Es un intervalo en el que siguen siendo posibles varios resultados materialmente distintos, y la respuesta correcta depende del sistema que tenga el dato que necesitas.

Aquí es donde un registro de auditoría demuestra su valor. Debe conservar lo que sabe el sistema local, demostrar que los registros retenidos no se han editado a escondidas y hacer visible la incertidumbre en lugar de ocultarla. No puede convertir una respuesta perdida en una prueba de que no se produjo una escritura en la base de datos, un pago, una implementación o un comando remoto.

Un tiempo de espera agotado es un vacío de pruebas, no un fallo confirmado

Un tiempo de espera agotado indica que uno de los participantes no observó una respuesta utilizable antes de su límite. No indica si el destino recibió la solicitud, si empezó a trabajar, si confirmó el trabajo o si la respuesta desapareció durante el trayecto de vuelta.

Mantén separados estos resultados en las notas del incidente y en cualquier interfaz que informe sobre las acciones del agente:

• Fallo confirmado: el destino o el ejecutor local devolvió pruebas duraderas de que rechazó o revirtió la operación solicitada.
• Éxito confirmado: el sistema que controla el estado modificado devolvió un recibo y una lectura posterior verifica el estado esperado.
• Resultado desconocido: la acción pudo haber ocurrido, pero las pruebas disponibles no permiten establecerlo en ningún sentido.
• No intentada: la pasarela rechazó la acción antes de entregarla a un ejecutor o transporte.

«Desconocido» no es una forma tímida de decir «probablemente falló». Es un estado operativo con un procedimiento distinto. Pausas los reintentos automáticos, conservas las pruebas, consultas el sistema autorizado y solo después decides si una acción compensatoria o un reintento es seguro.

A menudo se añade demasiado pronto una cuarta etiqueta, «éxito parcial». Úsala solo cuando puedas nombrar la suboperación completada y la incompleta. Una canalización de implementación que creó un artefacto, pero nunca lo promocionó, tiene un resultado parcial si ambos hechos están verificados. Una solicitud que desapareció después de que el cliente escribiera bytes en un socket tiene un resultado desconocido, aunque la solicitud pareciera sencilla.

RFC 9110 establece la misma distinción en términos de protocolo. Permite repetir automáticamente métodos idempotentes después de un fallo de comunicación porque repetir la operación prevista produce el mismo efecto previsto. También desaconseja reintentar automáticamente una solicitud no idempotente, salvo que el cliente pueda establecer que la solicitud original no se aplicó o sepa que la aplicación hace que las repeticiones sean seguras. Es una regla semántica, no un truco de transporte.

Una pasarela de acciones de agentes debe informar con precisión de los hechos locales. «Solicitud enviada; finalización no observada» resulta útil. «La acción falló» es una afirmación que el proceso local quizá no tenga derecho a hacer.

La pérdida de energía divide una acción en límites de durabilidad

Una acción puede atravesar varios límites antes de que alguien vea un resultado final. Escríbelos antes de probar, porque una prueba que solo detiene un proceso generará una confianza engañosa.

Una acción HTTP típica tiene al menos estos límites:

1. La pasarela acepta una intención autorizada y la registra localmente.
2. La pasarela construye la solicitud autenticada y empieza a transmitirla.
3. El servicio remoto recibe una parte suficiente de la solicitud para empezar a procesarla.
4. El servicio remoto confirma su efecto secundario y crea un recibo.
5. La pasarela recibe la respuesta y registra el resultado observado.

Una acción SSH sigue un recorrido parecido, con la diferencia de que el host remoto puede iniciar un comando antes de que el cliente local conozca su estado de salida. El host también puede crear procesos que sobrevivan a la sesión. Una conexión TCP o SSH correcta dice muy poco sobre el punto en el que se detuvo un comando.

Las escrituras locales tienen sus propios límites. Un proceso puede añadir un evento de auditoría, el sistema operativo puede aceptar ese añadido en la caché, el sistema de archivos puede ordenar los metadatos y los datos, y el almacenamiento puede hacer que los bytes sobrevivan a una pérdida de energía. No son acontecimientos intercambiables.

La especificación POSIX de fsync() indica que la llamada solicita transferir los datos pendientes de un archivo abierto a su dispositivo de almacenamiento y no devuelve el control hasta que la operación termina o informa de un error. Su justificación también advierte que la garantía real depende de la implementación y de la configuración del almacenamiento. Esa salvedad importa: una aplicación no puede deducir que una escritura es segura ante una pérdida de energía solo porque la llamada de escritura devolvió correctamente.

Para investigar, asigna a cada registro una clase de prueba en lugar de tratar todas las marcas temporales como igual de duraderas:

La tabla es deliberadamente estricta. Una línea del registro de procesos que dice «enviando solicitud» es una prueba de despacho. No es una prueba de entrega. Un cuerpo de respuesta que está en memoria es una prueba de observación. No es una prueba local duradera hasta que tu ruta de persistencia sobreviva al modelo de fallo que afirmas probar.

Asigna una identidad de operación a cada efecto secundario antes de probar los fallos

Un investigador no puede conciliar una acción interrumpida si el sistema remoto no tiene una forma estable de identificarla. Añade una identidad de operación antes de escribir una prueba de caos, no después de que aparezca el primer duplicado en producción.

Usa dos identificadores cuando puedas:

• Un identificador de acción generado localmente que nombre el intento individual de la pasarela.
• Un identificador de operación reconocido por el destino, una clave de idempotencia, un token de solicitud, un identificador de implementación o una referencia de transacción.

Pueden contener el mismo valor aleatorio, pero no des por hecho que significan lo mismo. El identificador de acción identifica un registro de auditoría local. El identificador remoto solo resulta útil cuando el destino lo guarda junto con el efecto secundario y ofrece una forma de recuperar el estado resultante.

En una API que admite claves de idempotencia, haz explícita la identidad en la solicitud y registra un resumen de la carga útil relevante. El resumen permite detectar que un operador intenta por accidente reutilizar una clave antigua con una solicitud modificada.

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"
}

No registres el encabezado de autorización, el token bearer ni un cuerpo completo que pueda contener secretos. Registra el método, la identidad del destino, los metadatos seguros de la solicitud, el identificador de acción, el identificador de operación y el resumen de la carga útil. Necesitas pruebas suficientes para comparar intentos sin crear otra filtración de credenciales en tu sistema de auditoría.

Un registro de intención útil podría tener este aspecto:

{
  "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"
}

Ese registro evita un fallo habitual en las investigaciones: alguien compara un reintento posterior con la primera acción usando solo la marca temporal y el endpoint, pasa por alto que cambiaron el artefacto o la cuenta y declara equivalentes dos operaciones distintas.

En SSH, coloca el identificador de operación donde el host remoto pueda conservarlo. Un comando de shell puede incluirlo en sus registros estructurados, un script de implementación puede escribirlo en un registro de versiones o un envoltorio remoto puede rechazar un identificador duplicado. No dependas de la transcripción del cliente SSH local como única prueba.

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

Si el comando inicia un trabajador en segundo plano, haz que el trabajador conserve el identificador de operación antes de cambiar nada. De lo contrario, una desconexión puede dejarte con un host que todavía está trabajando y sin una forma fiable de encontrar ese trabajo.

Simula interrupciones en los límites que cambian tu decisión

Una prueba de fallos útil detiene el proceso en puntos que llevan a decisiones distintas por parte del investigador. Terminar aleatoriamente un cliente en un bucle encuentra errores, pero no enseña a nadie qué significa el registro.

Construye un destino de prueba que pueda pausarse en fases controladas y responder a una consulta de conciliación mediante el identificador de operación. No tiene que ser sofisticado. Debe mostrar la diferencia entre solicitud recibida, efecto secundario confirmado y respuesta enviada.

Empieza con cinco casos:

1. Fallo antes de conservar la intención. La acción debe estar ausente del registro local duradero y del destino. Si el destino cambió, el orden de las operaciones es incorrecto o algún otro componente emitió la acción.
2. Fallo después de conservar la intención, pero antes del despacho. El registro de auditoría debe mostrar una acción aceptada sin registro de despacho. Solo debe clasificarse como no intentada si la pasarela puede demostrar que nunca entregó la acción a un transporte o ejecutor.
3. Fallo durante la transmisión de la solicitud. El destino puede no ver nada, ver una solicitud parcial o ver una solicitud completa. Clasifica el resultado como desconocido, salvo que el destino proporcione un rechazo definitivo o un resultado de consulta concluyente.
4. Fallo después de la confirmación remota, pero antes de conservar localmente la finalización. El destino debe mostrar la operación como completada mientras el registro local no contiene un evento de finalización. Esta es la prueba que revela una lógica de reintento peligrosa.
5. Fallo después de conservar localmente la finalización, pero antes de que el agente reciba la respuesta. El registro de auditoría local contiene la respuesta aunque el agente crea que se agotó el tiempo de espera. Una sesión nueva del agente debe consultar el registro de la acción en lugar de emitir a ciegas una segunda operación.

Un entorno local puede coordinar la pasarela y un servicio de prueba con archivos de pausa identificados por nombre. La implementación exacta variará, pero el contrato de la prueba no debería hacerlo. El entorno debe decirte a qué límite llegó antes de que lo interrumpas y conservar después el estado del destino para la conciliación.

# 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 prueba el fallo de un proceso. No prueba el comportamiento del almacenamiento ante un corte brusco de energía ni cancela una acción que el servicio remoto ya haya aceptado. Esa limitación resulta útil cuando estás aprendiendo a clasificar resultados. Obliga al equipo a dejar de tratar la muerte del emisor como una prueba sobre el receptor.

Para probar una pérdida de energía real, usa una máquina desechable o un entorno virtualizado en el que puedas reproducir apagados bruscos de forma segura. No tires del enchufe de una estación de trabajo que contenga la única copia de un almacén de producción, material de auditoría o un árbol de trabajo. Guarda la compilación exacta, el modo de almacenamiento, las entradas de prueba y la fuente temporal de cada ejecución. Un resultado de prueba sin ese contexto es una anécdota.

Un registro de auditoría debe indicar lo que sabe y conservar lo que no sabe

Un buen registro de auditoría se lee como un conjunto de afirmaciones con un alcance claro. No finge contener una verdad omnisciente sobre sistemas que no puede observar.

Para una acción interrumpida, registra eventos separados en lugar de sobrescribir un único campo de estado mutable. Una secuencia de solo adición puede representar la realidad sin inventar una respuesta 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

La tercera línea no debería decir remote_failed. Solo indica que la pasarela no pudo observar un resultado terminal. La cuarta línea añade una afirmación posterior procedente de la fuente que controla el estado de la versión.

Esta distinción también hace más útil la evidencia contra manipulaciones. Una cadena de hashes puede revelar cambios en el material de auditoría conservado, pero no puede recrear un evento que nunca llegó al almacenamiento duradero. Si una máquina pierde energía entre una llamada saliente y una adición al registro, una cadena intacta puede terminar limpiamente antes del resultado de la acción. Eso no significa necesariamente que la cadena esté rota. Es un vacío que necesita conciliación.

Sallyport proyecta sus diarios Sessions y Activity desde un único registro de auditoría cifrado, encadenado mediante hashes y ciego a la escritura, y sp audit verify comprueba esa cadena sin conexión sobre el texto cifrado. Esto proporciona al investigador una forma sólida de comprobar si el historial local conservado fue alterado, mientras deja el resultado remoto en manos de las pruebas remotas cuando sea necesario.

Mantén separadas las pruebas de autorización y las pruebas del resultado. Una aprobación demuestra que una persona o un control configurado permitió que una acción continuara. No demuestra que la acción terminara. Mezclar ambas afirmaciones es la forma en que un cambio de producción aprobado, pero interrumpido, acaba informándose falsamente como un cambio completado.

La misma advertencia se aplica a las marcas temporales. Las marcas del reloj de pared ayudan a correlacionar sistemas, pero no establecen un orden global cuando las máquinas discrepan o los búferes retrasan las escrituras. Si el orden importa, registra números de secuencia dentro de cada diario, conserva los identificadores de los recibos remotos y captura las marcas temporales propias del servicio durante la conciliación.

Las llamadas de red necesitan conciliación remota, no optimismo

Cuando una llamada HTTP pierde su respuesta, el destino suele ser la autoridad sobre si cambió el estado solicitado. Consúltalo antes de reintentar y haz que la consulta sea lo bastante específica para distinguir esta operación de trabajos parecidos.

El orden de conciliación más seguro es el siguiente:

1. Busca el identificador de operación o la clave de idempotencia en el destino.
2. Si el destino devuelve una operación completada, compara sus identificadores de recursos y el resumen de la carga útil con la intención original.
3. Si devuelve un rechazo registrado, conserva esa respuesta como prueba del fallo.
4. Si no tiene ningún registro, comprueba si la API documenta procesamiento diferido, colas asíncronas o creación eventual del registro antes de emitir un reintento.
5. Reintenta solo cuando la semántica del endpoint y las pruebas hagan segura la repetición.

No confundas una solicitud GET con una verificación inofensiva solo porque usa un método seguro. Algunas API ocultan trabajo detrás de un endpoint de lectura y algunas cachés de respuestas van por detrás de la ruta de escritura. Verifica el contrato del proveedor y, cuando sea posible, recupera el recurso creado específico o el registro de operación en lugar de buscar en una lista amplia por hora.

Las etiquetas de los métodos HTTP ayudan, pero no resuelven el comportamiento de la aplicación. Una solicitud PUT puede ser idempotente en la capa HTTP mientras el servidor envía correos duplicados, cobra el uso o activa un enlace de implementación en cada recepción. RFC 9110 señala expresamente que la idempotencia se aplica al efecto solicitado, mientras que un servidor puede conservar registros separados o producir otros efectos secundarios. Por eso importa más la identidad de operación documentada por el responsable de la API que un verbo en una biblioteca cliente.

Una recomendación popular, pero mala, es «reintenta dos veces cada tiempo de espera agotado». Suena práctica porque muchos tiempos de espera son transitorios. Convierte un problema transitorio de transporte en un movimiento de dinero duplicado, una creación de cuenta duplicada o dos versiones de producción cuando el endpoint no admite repeticiones seguras. Una política de reintentos debe especificar el tipo de operación, el mecanismo de idempotencia, el retraso máximo y las pruebas que permiten reintentar.

Si un servicio remoto no ofrece consulta ni soporte de idempotencia, la respuesta honesta puede ser que no puedes resolver automáticamente el resultado. Crea un proceso compensatorio alrededor de esa limitación, como una cola de revisión humana con la huella exacta de la solicitud y una cuenta de solo lectura que pueda inspeccionar el estado afectado.

Los comandos SSH necesitan pruebas del host remoto

Una sesión SSH interrumpida deja más ambigüedad que muchas llamadas de API porque el comando puede ejecutarse en el otro extremo después de que el cliente desaparezca. La pérdida del estado de salida no significa que el comando fallara. Significa que falta una observación.

Evita una única línea de shell grande que haga varias modificaciones sin puntos de control. Divide el trabajo remoto en operaciones con sus propios identificadores y estado duradero. Un envoltorio de implementación, por ejemplo, puede registrar received, validated, applied y completed para un identificador de operación y ofrecer después un comando de estado de solo lectura.

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

El envoltorio debe escribir su estado antes de iniciar una acción no repetible, no después. Si asigna un recurso en la nube, publica un paquete o cambia el tráfico, debe conservar el recibo del proveedor con el mismo identificador de operación. Si no puede hacerlo, coloca la operación detrás de una cola remota que sí pueda.

Desconfía de los traps de limpieza del shell como pruebas de recuperación. Un trap local no se ejecuta después de una pérdida brusca de energía. Un trap remoto puede no ejecutarse después de una terminación forzada y puede ejecutarse mientras un proceso hijo continúa. La lógica de limpieza puede reducir el desorden, pero no demuestra el estado final.

Usa un marcador remoto solo cuando el marcador y el efecto secundario tengan una relación significativa. Una línea añadida a /tmp/action-done no demuestra que se haya confirmado una migración de base de datos. Una entrada en la tabla de migraciones escrita en la misma transacción es una prueba mejor. Un registro de implementación creado por el controlador de implementaciones es aún mejor.

Sallyport enruta SSH mediante su asistente sin estado incluido sp-ssh, pero se aplica la misma regla: el registro de acción local puede establecer lo que la pasarela intentó y observó. Solo el host remoto, o el sistema modificado por el comando, puede resolver un resultado remoto no observado.

Guía al investigador por una versión interrumpida

Supongamos que un agente solicita una versión de producción mediante un endpoint HTTP. La pasarela registra una intención autorizada con el identificador de acción act_01JX8F3Z6Z, el identificador de operación 8b4d..., el resumen del artefacto 3c1f... y una aprobación de sesión. Empieza la solicitud. El servicio de versiones confirma la versión y asigna el recibo rel_4921. Antes de que la respuesta llegue a la pasarela, el portátil pierde energía.

Después de reiniciar, la transcripción del agente indica que la llamada agotó el tiempo de espera. El registro de auditoría local termina en transport_started. Alguien que trate esa línea como una prueba de fallo envía la misma versión otra vez, esta vez con un identificador de operación nuevo. El servicio crea una segunda versión. Si el endpoint activa la versión de inmediato, la segunda solicitud puede ser solo ruido. Si activa una migración irreversible, puede resultar costosa.

La investigación correcta empieza bloqueando el reintento automático de act_01JX8F3Z6Z. Verifica la cadena de auditoría local. Registra el último evento conservado, las pruebas de terminación del proceso local, el destino, el resumen de la carga útil y el identificador de operación. Después consulta 8b4d... en el servicio de versiones.

Hay tres resultados útiles:

• El servicio devuelve rel_4921 con el resumen de artefacto 3c1f.... Clasifica la acción original como éxito confirmado después de la conciliación. La finalización local ausente sigue siendo un vacío de auditoría, no un motivo para volver a ejecutar la versión.
• El servicio devuelve un rechazo duradero asociado a 8b4d.... Clasifícalo como fallo confirmado. Conserva el motivo del rechazo antes de decidir si corresponde enviar una solicitud corregida.
• El servicio no devuelve ningún registro. Comprueba si pone las solicitudes en cola antes de crear registros de operación y si la ruta de consulta tiene retraso. Si no puede descartar un trabajo diferido, conserva el resultado desconocido y escala el caso en lugar de emitir un reintento a ciegas.

Observa qué cosas no deciden el caso: el tiempo de espera agotado del agente, la salida del proceso de la pasarela o el hecho de que una persona aprobara la acción. Esos hechos importan, pero ninguno controla el estado de la versión.

Este recorrido también revela un requisito de diseño. Si el destino no permite buscar por identificador de operación, la pasarela debe evitar acciones no repetibles desatendidas contra ese destino o exigir una ruta de conciliación humana. La calidad de la auditoría no puede compensar una API que no ofrece una forma duradera de identificar sus propios efectos secundarios.

Las reglas de reintento deben ser lo bastante estrictas para resistir un mal día

Una política de reintentos debe decir algo más que «reintentar ante errores de red». Escríbela como una tabla de decisiones que puedan seguir tanto quien implementa el sistema como quien responde a un incidente.

No permitas que los agentes inventen un identificador de operación nuevo durante la recuperación. Es un generador sutil de duplicados. Si un reintento es válido, reutiliza la misma identidad reconocida por el destino y demuestra que la carga útil coincide con la intención original. Si ha cambiado el cambio deseado, se trata de una acción nueva que merece una decisión de autorización nueva.

Establece un estado terminal para las acciones no resueltas. «Desconocido, pendiente de conciliación» es mejor que un trabajo que reintenta para siempre porque nadie escribió la máquina de estados para admitir la incertidumbre. Asigna a ese estado una persona responsable, un plazo y una vía de escalado. De lo contrario, una acción ambigua antigua se convierte en una sorpresa cuando alguien la revisa semanas después con registros remotos incompletos.

Conserva las pruebas antes de que los sistemas dejen de tener la respuesta

La primera hora después de una interrupción es cuando los servicios remotos todavía tienen trazas de solicitudes, entradas de cola y el contexto reciente de los operadores. Captura los hechos antes de que la retención de registros, la expulsión de cachés o alguna otra implementación los elimine.

Conserva el material de auditoría local en su forma original y verifícalo antes de copiar fragmentos en un ticket. Registra el identificador de acción exacto, el identificador de operación, el destino, el resumen de la carga útil, el registro de autorización, el último evento local y la hora del reinicio local. Después recopila el registro de operación remoto, la revisión del recurso, el identificador de solicitud del proveedor y la fuente temporal del servicio utilizada para responder.

No repares el historial añadiendo un evento de finalización falso. Añade un evento posterior de conciliación que indique su origen y sus pruebas. Los investigadores necesitan ver el límite original, porque ese límite les dice qué sabía el sistema en ese momento.

La lección duradera resulta incómoda, pero es sencilla: una acción auditada puede estar bien autorizada, registrarse con cuidado y aun así tener un resultado remoto desconocido después de una pérdida de energía. Crea identidades de acción, recibos remotos y rutas de conciliación antes de permitir que un agente autónomo realice trabajos que no puedan ejecutarse dos veces de forma segura. Cuando las luces se apagan en el momento equivocado, esas decisiones determinan si tu equipo investiga un vacío o crea un segundo incidente.