# Qué pasa cuando algo falla

> Cada salto del motor con lo que puede fallar en él, dónde esperan los datos mientras tanto, cuántas veces se intenta, a dónde va lo que no se pudo hacer, a quién se le avisa y cómo se vuelve a procesar. Colas, colas de mensajes fallidos y salud, en las dos formas de despliegue.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/architecture/reliability/

Para agentes: Lee esto para conocer la garantía de entrega del motor (al menos una vez entre pasos, pasos idempotentes), la tabla de fallas por salto, la cola de entrada y su cola de mensajes fallidos en AWS (retención, tiempo de invisibilidad, máximo de entregas, redrive, alarmas), el búfer en memoria de la forma de un solo proceso, la cuarentena de segmentos envenenados, el trabajo como filas en Postgres (tareas, liberación de alertas, entregas de webhook), GET /healthz, GET /v1/engine/status y sypnia doctor.

Esta página responde una pregunta: **¿el motor es frágil?** Recorre cada salto que da un evento y dice qué puede fallar ahí, dónde esperan los datos mientras falla, cuántas veces se intenta, a dónde va lo que no se pudo hacer, a quién se le avisa y el comando exacto que lo vuelve a procesar.

> **En palabras simples**
>
> Nada de lo que tu app envió, y el motor aceptó, se bota porque un paso falló. Cada paso termina su trabajo o lo deja donde el siguiente intento lo encuentra: en el navegador por unos segundos, en una cola, en un archivo o en una fila con una hora. El trabajo que falla cinco veces se aparta con su error escrito, para que un archivo malo nunca bloquee tu proyecto ni el de nadie más, y se te avisa. Lo que sí se puede perder está al final de esta página, y es corto: los eventos que tu app no alcanzó a entregar mientras el motor no respondía.

> **Nota: Sobre los números y el código**
>
> Los tiempos y las cantidades de esta página son reglas del diseño: las pruebas las hacen cumplir. Ninguno es una medición del motor en Rust, que aún no se ha publicado. El Rust y el SQL son extractos de diseño; el repositorio se abre al lanzar. Los incidentes citados son del sistema del que sale este motor.

## La garantía

**Entre pasos, al menos una vez. Dentro de un paso, se puede repetir sin daño. Juntas: cada evento se cuenta una vez.**

Ningún paso del motor confía en que corre exactamente una vez. Las funciones se reintentan, las colas entregan dos veces, a los procesos los matan después de hacer el trabajo y antes de decirlo. En vez de fingir lo contrario, el motor hace que la segunda corrida no cause daño. Lo logran tres mecanismos, y los tres están en las páginas anteriores:

| Mecanismo                                                              | Qué protege                                                                                                                                                                             | Dónde                                                                                                                                                  |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`batch_id`** en cada línea guardada                                  | Un lote que llega dos veces, porque un SDK reintentó o una cola entregó dos veces, se guarda y nunca se cuenta dos veces                                                                | [Ingesta](https://docs.sypnia.com/es/architecture/ingest#duplicados-e-idempotencia)                                                                    |
| **El registro**: una fila por segmento, con `scanned_at` y `rolled_at` | Un segmento lo revisa un solo worker, y sus contadores se suman en la misma transacción que lo marca. Pasan las dos cosas o ninguna                                                     | [Agregación](https://docs.sypnia.com/es/architecture/aggregation#exactamente-una-vez-el-registro)                                                      |
| **Upserts y llaves únicas**                                            | Un problema tiene una fila por huella; una alerta tiene una fila por causa (`dedupe_key`); una tarea tiene una fila abierta por problema; los números de una hora se reemplazan enteros | [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping), [Almacenamiento](https://docs.sypnia.com/es/architecture/storage) |

La guarda contra duplicados es una sola sentencia. Fíjate en que no necesita candado ni una lectura previa de «¿ya lo vi?»: la llave primaria responde, y los ids que **no** se insertaron son los duplicados.

`crates/sypnia-db/sql/batches_record.sql`

```sql
-- La corre la vía rápida dentro de la transacción que marca el segmento como revisado.
-- $3 = los ids de lote que trae el segmento. Devuelve los que son nuevos.
INSERT INTO ingest_batches (project_id, batch_id, segment)
SELECT $1, batch_id, $2
  FROM unnest($3::text[]) AS t(batch_id)
ON CONFLICT (project_id, batch_id) DO NOTHING
RETURNING batch_id;
-- Todo id de $3 que no volvió ya pertenece a un segmento anterior.
-- Esos van a segments.skipped, y desde entonces todo lector salta sus líneas.
```

La segunda mitad de la garantía es que **el trabajo nunca queda solo en memoria una vez aceptado**. En todo momento un evento aceptado está en uno de cuatro lugares durables:

| Lugar                                                   | Guarda                                                                                   | Por cuánto tiempo                             |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------- |
| La cola de entrada **\[Motor]** solo en la forma de AWS | Lotes validados que aún no están en un segmento                                          | Segundos, normalmente; hasta 4 días           |
| El Bucket                                               | Segmentos, fragmentos de grabación, archivos por sesión                                  | Hasta que la retención los borra              |
| El registro en Postgres                                 | Qué segmentos existen, cuáles están revisados, cuáles están consolidados                 | Lo mismo que el segmento                      |
| Una fila con una hora                                   | Tareas del agente, alertas retenidas, entregas de webhook, horas por consolidar de nuevo | Hasta que se hace, o se marca como abandonada |

La figura que sigue es el flujo de datos de la [página anterior](https://docs.sypnia.com/es/architecture/data-flow) dibujado para esta pregunta: cada flecha que puede fallar tiene su ciclo de reintento, cada lugar de espera está marcado y se muestra cada salida para el trabajo que no se pudo hacer.

**Figura (diagrama aún sin dibujar)**: El flujo de datos con cada ciclo de reintento, cada lugar donde el trabajo espera y cada salida para lo que no se pudo hacer. Nada sale del dibujo: lo apartado sigue visible y se puede volver a procesar.

Mostrará: DIAGRAMA DE FLUJO, de izquierda a derecha, con los mismos nodos y nombres del diagrama «hops» de architecture/data-flow, redibujado para mostrar el manejo de fallas. NODOS en orden: «Tu app (SDK)» · «Ingesta» · un lugar de espera dibujado como una bandeja pequeña con el rótulo «Cola de entrada (AWS) / búfer, 2 s (un proceso)» · «Bucket» · «Vía rápida» · «Consolidación» (debajo de la Vía rápida, ambas leen del Bucket) · «Postgres» · «El agente» · «Alertas» · «Tu webhook» (punteado, fuera del motor) · y en un carril inferior «API · servidor MCP · Consola» leyendo de Postgres y del Bucket. EN CADA FLECHA QUE PUEDE FALLAR dibuja un ciclo de reintento circular pequeño con un rótulo corto, textos exactos: en SDK → Ingesta «reintento 1 s, 4 s, 15 s · mismo batch_id»; en Ingesta → cola/Bucket «503: el SDK reintenta»; en cola → Bucket (el worker escribe el segmento) «se entrega de nuevo: 15 s, 1 min, 5 min, 15 min»; en Bucket → Vía rápida «reserva de 2 min · 5 intentos»; en Bucket → Consolidación «siguiente pasada, luego 1, 5, 15, 30 min»; en Vía rápida → El agente «3 intentos: 5 s, 30 s»; en Alertas → Tu webhook «7 intentos en 21 horas»; en API → lector «503 + Retry-After». LUGARES DE ESPERA dibujados como bandejas con un ícono de reloj, rótulos exactos: bajo Tu app «cola de 500 eventos en memoria»; la bandeja de la cola de entrada «hasta 4 días»; bajo Bucket «los segmentos esperan aquí mientras Postgres está caído»; bajo Postgres «filas con una hora: tareas, alertas retenidas, entregas». SALIDAS para el trabajo que no se pudo hacer, dibujadas como flechas punteadas que BAJAN a un carril inferior titulado «Apartado, visible, se puede volver a procesar», con cuatro cajas, rótulos exactos: «Cola de mensajes fallidos (AWS) · 14 días» (desde la cola de entrada), «Segmento en cuarentena» (desde la Vía rápida y la Consolidación), «analysis.status = failed» (desde El agente), «entrega fallida» (desde Alertas). De cada una de las cuatro cajas, una flecha delgada de regreso hacia arriba a su origen con el rótulo de cómo se vuelve a procesar: «redrive», «sypnia aggregate --from … --to …», «POST …/analyze», «POST …/retry». El elemento encendido es el carril inferior. Una marca pequeña en el Bucket: «los eventos aceptados están a salvo desde aquí» (en AWS, una segunda marca más tenue en la cola de entrada: «en AWS: desde aquí»). Llamadas numeradas (1) a (9) en los saltos, en el orden de la tabla que sigue.

## Salto por salto

Una fila por salto. «Intentos» cuenta el primero. Las secciones después de la tabla entran en las filas que lo necesitan.

| #  | Salto                                              | Qué puede fallar                                                                                                         | Qué pasa, y dónde esperan los datos                                                                                                                                                                                                                                                     | Se rinde después de, y va a                                                                                                  | A quién se le avisa                                                                                                       | Cómo se vuelve a procesar                                                                                    | Qué ves mientras tanto                                                                                           |
| -- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| 1  | Tu app (SDK) → Ingesta                             | La Ingesta no responde, `429`, `503`, se agota el tiempo                                                                 | El SDK del navegador conserva el lote y lo envía de nuevo a 1 s, 4 s y 15 s con el mismo `batch_id`, y después con el siguiente envío cada 10 s. Los eventos esperan en su cola: 500 eventos en memoria, salen primero los más viejos. Los SDK de servidor reintentan y luego descartan | La cola de 500 se llena, o la pestaña se cierra: esos eventos se pierden                                                     | A nadie de inmediato. El hueco se ve como un `data_through` que no avanza; un monitor tuyo sobre `/healthz` lo ve primero | No se puede: los datos nunca llegaron                                                                        | Leer sigue funcionando. No hay datos nuevos                                                                      |
| 2  | Ingesta → la cola o el búfer                       | La cola rechaza el envío (AWS). El búfer está lleno: 32 MiB esperando en total, u 8 MiB de un solo proyecto (un proceso) | La Ingesta responde `503 unavailable` con `Retry-After: 2`. No guardó nada, así que el reintento del SDK del salto 1 lo cubre                                                                                                                                                           | Como el salto 1                                                                                                              | La línea de log de la Ingesta; `engine.failing` si dura 30 minutos                                                        | No hace falta                                                                                                | Como el salto 1                                                                                                  |
| 3  | La cola o el búfer → Bucket                        | El Bucket rechaza la escritura                                                                                           | **Un proceso:** los lotes de ese segmento reciben `503` y sus SDK reintentan. **AWS:** el mensaje se queda en la cola y se entrega de nuevo a los 15 s, 1 min, 5 min y 15 min                                                                                                           | **AWS:** 5 entregas, y luego la cola de mensajes fallidos, donde se guarda 14 días                                           | La alarma de mensajes fallidos; la alarma de antigüedad de la cola; `engine.failing`                                      | Redrive: un comando, [más abajo](#redrive)                                                                   | Las listas y los problemas se siguen leyendo de Postgres. Las grabaciones y las líneas de tiempo responden `503` |
| 4  | Ingesta o worker → Postgres (la fila del registro) | Postgres caído, sin conexiones libres                                                                                    | **Un proceso:** la fila se conserva y se reintenta; el segmento ya está en el Bucket. **AWS:** el mensaje no se borra hasta que la fila exista, así que la cola lo entrega de nuevo                                                                                                     | **Un proceso:** nunca se rinde; al reiniciar encuentra el segmento listando el Bucket. **AWS:** como el salto 3              | `engine.failing` a los 30 minutos                                                                                         | Nada que hacer. Después de restaurar un respaldo: `sypnia aggregate --from <hora>` vuelve a listar el Bucket | Los eventos están a salvo y aún no se cuentan                                                                    |
| 5  | Bucket → Vía rápida → Postgres                     | El objeto no se puede leer; una línea que rompe al lector; la transacción falla; el worker muere a mitad de la revisión  | La reserva del segmento vence a los 2 minutos, o se devuelve con una espera de 10 s, 30 s, 2 min, 5 min. Otro worker lo toma. El segmento espera en el Bucket, su fila en el registro                                                                                                   | 5 intentos, y luego **cuarentena**: `quarantined_at` y el error en su fila del registro                                      | Una alerta `engine.failing` que nombra el segmento, de inmediato                                                          | `sypnia aggregate --project <p> --from <t> --to <t>` le da cinco intentos nuevos                             | Todo lo demás del proyecto, y todos los demás proyectos, fluyen. Los eventos de ese segmento no se cuentan       |
| 6  | Bucket → Consolidación → Postgres                  | Se pasa del presupuesto de memoria, un error de lectura, el commit falla, el worker muere                                | No se escribió nada: la corrida es una transacción. La hora se marca `failed` y se intenta de nuevo en la siguiente pasada, luego a 1, 5 y 15 minutos, y después cada 30                                                                                                                | Nunca, dentro de 48 horas. Una corrida que falla 5 veces en el mismo segmento pone ese segmento en cuarentena y sigue sin él | `engine.failing` a los 30 minutos, con el proyecto y la hora                                                              | Sola; o `sypnia aggregate --from … --to …` para horas de más de 48 horas                                     | Los problemas llegan a tiempo. Los números de ese proyecto y esa hora llegan tarde                               |
| 7  | Vía rápida → el agente → el proveedor de IA        | El proveedor responde un error, se agota el tiempo (60 s) o devuelve una respuesta que no pasa la revisión               | La tarea es una fila. Se intenta de nuevo a los 5 s y a los 30 s. La alerta no espera: sale en su `release_by` con el título técnico                                                                                                                                                    | 3 intentos, y luego la tarea queda `dead` y el problema muestra `analysis.status: failed` con el motivo                      | El problema mismo, en la API, el servidor MCP y la Consola                                                                | `POST /v1/problems/{problem}/analyze`; o sola cuando el problema crece                                       | El problema, sus conteos, su alerta y su prompt, sin la frase                                                    |
| 8  | Postgres → Alertas                                 | El worker muere entre escribir la alerta y liberarla                                                                     | La alerta es una fila con `release_by`. Cualquier pasada libera lo que ya pasó su hora; liberar es un `UPDATE … WHERE released_at IS NULL`                                                                                                                                              | Nunca                                                                                                                        | —                                                                                                                         | No hace falta                                                                                                | La alerta, máximo una pasada tarde                                                                               |
| 9  | Alertas → tu webhook                               | Tu receptor está caído, lento (10 s) o responde algo que no es `2xx`                                                     | La entrega es una fila. 7 intentos: de inmediato, y luego a 1 min, 5 min, 30 min, 2 h, 6 h y 12 h, con el mismo id de evento                                                                                                                                                            | 7 intentos, y luego la entrega queda `failed`. Tras 3 días de puras fallas el webhook se apaga                               | `GET /v1/webhooks/{id}/deliveries`; una alerta `engine.failing` cuando el webhook se apaga                                | `POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry`; `PATCH` al webhook para encenderlo          | La alerta queda registrada y se ve en la Consola y la API todo el tiempo                                         |
| 10 | Postgres y Bucket → API, servidor MCP, Consola     | Postgres no tiene conexiones libres; el Bucket no responde                                                               | `503 unavailable` con `Retry-After: 2`, de inmediato. La API no hace cola                                                                                                                                                                                                               | —                                                                                                                            | Quien llama                                                                                                               | Quien llama reintenta                                                                                        | Un error con un tiempo de espera, nunca un número equivocado                                                     |
| 11 | La programación → el worker (AWS)                  | Una marca del minuto se pierde, llega tarde o llega dos veces                                                            | La siguiente, un minuto después, hace todo lo que habría hecho la perdida: todo el trabajo pendiente son filas                                                                                                                                                                          | Nunca                                                                                                                        | La alarma del worker, si la función misma falla                                                                           | No hace falta                                                                                                | Máximo un minuto más de demora                                                                                   |

Tres cosas valen para todas las filas:

- **Quien envía conserva el trabajo hasta que quien recibe lo tiene de forma durable.** El SDK conserva el lote hasta el `200`; la cola conserva el mensaje hasta que el worker lo borra; el registro conserva el segmento hasta que su transacción confirma.
- **Rendirse es un estado, no una desaparición.** Una cola de mensajes fallidos, un segmento en cuarentena, una tarea `dead` y una entrega `failed` son cosas que puedes listar, leerles el error y enviar de nuevo.
- **Una falla demora; no corrompe.** Un paso que corre dos veces escribe el mismo resultado. Es la regla 3 del [resumen](https://docs.sypnia.com/es/architecture#3-todo-paso-puede-correr-dos-veces-sin-da%C3%B1o), y las pruebas de reproducción de [el código](https://docs.sypnia.com/es/architecture/codebase#pruebas-que-repiten-horas-grabadas) corren cada paso dos veces para probarlo.

## Las fallas, una por una

### La Ingesta está caída

Los SDK guardan lo que pueden (salto 1) y leer no se afecta: la API, el servidor MCP y la Consola no dependen de la Ingesta. En AWS «la Ingesta está caída» quiere decir que la función falla o llegó a su tope de 40 copias; la dirección responde `503` o `429` y los SDK reintentan. En la forma de un solo proceso quiere decir que el proceso está caído, y la API con él, salvo que corras los roles por separado.

Se pierde lo que el SDK no pudo guardar: más de 500 eventos en una pestaña, una pestaña que se cerró, el último lote de una página que se envió con `sendBeacon` y no tuvo respuesta. El motor no puede saber de eventos que nunca recibió, así que esta pérdida solo se ve como un hueco.

### El Bucket está caído

La Ingesta responde `503` y no acepta nada que no esté guardado, así que no hay nada que recuperar: los SDK reintentan. En AWS, los lotes que ya están en la cola esperan ahí. Leer de Postgres sigue funcionando: la lista de problemas, un problema, los números, las alertas. Todo lo que necesita un objeto responde `503`: grabaciones, la línea de tiempo de una sesión, el detalle de una traza.

### Postgres está caído

Se sigue recibiendo. La Ingesta no consulta Postgres: usa su caché de llaves, que sigue siendo válida hasta una hora sin refrescarse. Los segmentos se escriben; la vía rápida, la consolidación y la API se detienen. Cuando Postgres vuelve, el worker toma todo lo no revisado, lo más viejo primero y un proyecto a la vez por turnos, y consolida cada hora abierta.

| Forma            | Dónde esperan los eventos durante la caída                                                                                                                                                                              | Si dura                                                                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Un proceso       | En el Bucket, como segmentos. Sus filas del registro se conservan en memoria y se reintentan; un worker que arranca lista las últimas dos horas de cada proyecto y agrega cualquier segmento que el registro no conozca | Más de una hora: la Ingesta responde `503`, porque su caché de llaves es demasiado vieja para confiar en ella                                          |
| Funciones de AWS | En la cola de entrada. Un mensaje solo se borra cuando existen su segmento **y** su fila del registro                                                                                                                   | Más de unos 20 minutos: los lotes llegan a su quinta entrega y pasan a la cola de mensajes fallidos, donde esperan hasta 14 días un comando de redrive |

Lo que Postgres guarda y el Bucket no puede devolver es lo que escribió la gente: estados, notas, reglas, llaves, tokens. Para eso son sus respaldos. Todo lo que viene de eventos se reconstruye con `sypnia aggregate --from … --to …`.

### Un lote o un segmento envenenado

Una entrada «envenenada» es la que falla cada vez que se intenta: un objeto cortado, una línea que dispara un error en un lector, un valor que una tabla rechaza. El peligro no es el segmento perdido. Es un worker que lo toma, muere, lo vuelve a tomar y nunca llega al trabajo que hay detrás.

Tres capas lo impiden:

1. **Un evento malo nunca se vuelve un segmento malo.** La Ingesta juzga cada evento por separado: lo recorta, lo limpia o lo descarta, y lo dice en la respuesta. Una línea que aun así no se puede interpretar al leerla se cuenta (`unreadable`) y se salta. Ninguna de las dos cosas detiene nada.
2. **Un mensaje malo no bloquea la cola** (AWS). El worker le responde a la cola con la lista de los mensajes que no pudo escribir, no con una sola falla para toda la entrega. Los buenos se borran; uno malo vuelve solo y, tras 5 entregas, va a la cola de mensajes fallidos.
3. **Un segmento malo queda en cuarentena.** Cada reserva cuenta un intento. Un segmento que se reservó 5 veces y nunca se revisó se marca con `quarantined_at`, con el último error, y ningún lector lo vuelve a tomar.

**Figura (diagrama aún sin dibujar)**: Un segmento envenenado. Se intenta cinco veces con esperas crecientes mientras todo a su alrededor se revisa, y luego se aparta con su error. El objeto mismo nunca se toca.

Mostrará: DIAGRAMA DE CARRILES, el tiempo va de izquierda a derecha, tres carriles horizontales. CARRIL 1 «Segmentos de prj_5k2m9x4q7w1z (shop)»: cinco fichas de archivo en fila con los rótulos «…091207Z», «…091216Z», «…091744Z» (esta dibujada agrietada, en el tono de advertencia), «…091902Z», «…092015Z». CARRIL 2 «Vía rápida»: bajo cada ficha sana una marca de visto y una flecha hacia abajo a una franja «Postgres» al fondo con el rótulo «problemas, registro: scanned_at». Bajo la ficha agrietada, cinco marcas pequeñas de intento en fila con las esperas entre ellas, rótulos exactos: «intento 1 · falla», «+10 s · intento 2», «+30 s · intento 3», «+2 min · intento 4», «+5 min · intento 5», y luego una flecha punteada ABAJO-DERECHA hacia una caja lateral con el rótulo «En cuarentena · quarantined_at, error: unexpected end of gzip stream». De la caja lateral salen dos flechas: una a un ícono de campana con el rótulo «alerta engine.failing, nombra el segmento», y una flecha curva de regreso a la ficha agrietada con el rótulo «sypnia aggregate --project shop --from 09:00 --to 10:00 → cinco intentos nuevos». CARRIL 3 «Otros proyectos»: una fila de fichas pequeñas de un segundo proyecto «prj_9c1t4h8n2b6d», todas con marca de visto, y la nota «los turnos son por proyecto: nadie espera detrás del segmento malo». Las fichas «…091902Z» y «…092015Z» del carril 1 deben verse revisadas MIENTRAS la ficha agrietada todavía se está reintentando (pon sus marcas de visto bajo los intentos 2 y 3). El elemento encendido es la caja lateral «En cuarentena». Llamadas numeradas: (1) la ficha agrietada, (2) los cinco intentos, (3) la caja de cuarentena, (4) el carril 3.

Toda la decisión es la función de abajo. Fíjate en que el intento ya lo contó la reserva, así que un worker que muere antes de llegar a este código igual gasta un intento.

`crates/sypnia-pipeline/src/fast_path.rs`

```rust
const MAX_ATTEMPTS: u32 = 5;

/// Cuánto espera un segmento que falló antes de su siguiente intento.
fn backoff(attempts: u32) -> Duration {
    match attempts {
        0 | 1 => Duration::from_secs(10),
        2 => Duration::from_secs(30),
        3 => Duration::from_secs(120),
        _ => Duration::from_secs(300),
    }
}

/// La llama `run` cuando `scan_segment` devolvió un error. Un segmento malo nunca termina la pasada.
async fn give_back(engine: &Engine, segment: &Segment, error: &EngineError) -> Result<Outcome, EngineError> {
    if segment.attempts < MAX_ATTEMPTS {
        // Suelta la reserva antes de tiempo, con una espera. Puede que otro worker sí lo logre.
        engine.db.release_segment(segment, backoff(segment.attempts), &error.to_string()).await?;
        return Ok(Outcome::Retrying);
    }
    // Fuera del camino de todo lector. El objeto se queda donde está; la hora se consolida sin él.
    let mut tx = engine.db.begin().await?;
    tx.quarantine_segment(segment, &error.to_string()).await?;
    alerts::record_engine_failing(&mut tx, Failing::Quarantined(segment), engine.clock.now()).await?;
    tx.commit().await?;
    Ok(Outcome::Quarantined)
}
```

Un segmento en cuarentena son 2 segundos de eventos de un proyecto, máximo 4 MiB. Sus eventos no están en ningún conteo hasta que alguien lo vuelva a procesar. Para hacerlo, casi siempre después de actualizar a una versión que corrige al lector:

```bash
sypnia aggregate --project shop --from 2026-03-12T09:00:00Z --to 2026-03-12T10:00:00Z
```

Volver a procesar un rango quita la cuarentena de los segmentos que hay en él, le da a cada uno cinco intentos nuevos, y agrega al registro cualquier segmento del rango que esté en el Bucket y no en el registro. Nada se cuenta dos veces: los segmentos que ya se habían sumado conservan su `rolled_at`.

### Un proyecto lento

Un proyecto no debe atrasar a los demás, envíe lo que envíe. Cada parte tiene su propia guarda:

| Parte         | Qué podría acaparar un proyecto pesado                | La guarda                                                                                                                                                                                                                                                                                                                    |
| ------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ingesta       | El búfer                                              | Un segmento abierto por proyecto. De los 32 MiB que pueden esperar en total, un proyecto puede tener 8 MiB; pasado eso, **sus** lotes reciben `503`, los de los demás no. Los límites de frecuencia son por llave                                                                                                            |
| Vía rápida    | El tiempo del worker                                  | Turnos. Cada reserva va al proyecto que lleva más tiempo sin ser atendido, y toma un segmento. Un proyecto con mil segmentos atrasados recibe un turno por ronda, igual que un proyecto con uno                                                                                                                              |
| Consolidación | La memoria y las corridas de `processing.concurrency` | 256 MB por corrida, de forma obligatoria; una corrida que se pasa de su presupuesto se detiene y marca la hora `failed`. Los proyectos se toman empezando por el que lleva más tiempo sin consolidar, y una hora fallida espera 1, 5, 15 y luego 30 minutos entre intentos, así que no puede ocupar una corrida para siempre |
| El agente     | Llamadas al modelo                                    | 100 análisis al día por proyecto y 3 por problema; una tarea abierta por problema                                                                                                                                                                                                                                            |
| API           | Conexiones                                            | Un grupo pequeño y acotado; `503` con `Retry-After` en vez de una cola                                                                                                                                                                                                                                                       |

La reserva es una sola sentencia. Fíjate en el orden: primero por cuándo tuvo su último turno el proyecto, y luego por antigüedad. El índice que lee solo contiene segmentos que están esperando, así que es pequeño por construcción.

`crates/sypnia-db/sql/segment_lease.sql`

```sql
-- $1 = la reserva (2 minutos). Devuelve un segmento, o ninguno.
WITH pick AS (
    SELECT s.project_id, s.key
      FROM segments s
      LEFT JOIN project_turns t USING (project_id)
     WHERE s.scanned_at IS NULL
       AND s.quarantined_at IS NULL
       AND (s.leased_until IS NULL OR s.leased_until < now())  -- libre, ya esperó, o su worker murió
     ORDER BY t.fast_path_at NULLS FIRST, s.created_at
     LIMIT 1
       FOR UPDATE OF s SKIP LOCKED                              -- dos workers nunca reciben el mismo
), turn AS (
    INSERT INTO project_turns (project_id, fast_path_at)
    SELECT project_id, now() FROM pick
    ON CONFLICT (project_id) DO UPDATE SET fast_path_at = EXCLUDED.fast_path_at
)
UPDATE segments s
   SET leased_until = now() + $1,
       attempts     = s.attempts + 1                            -- se cuenta aquí, antes de cualquier trabajo
  FROM pick
 WHERE s.project_id = pick.project_id AND s.key = pick.key
RETURNING s.*;
```

### El proveedor de IA falla o está lento

El agente es la única parte que espera a un servicio que el motor no controla, así que nada más espera al agente. La alerta se libera en su `release_by`, exista o no la frase. Una llamada tiene 60 segundos (`ai.timeout_seconds`); una tarea tiene 3 intentos, a los 5 y a los 30 segundos; después la tarea queda `dead` y el problema dice `analysis.status: failed` con el error del proveedor. Cuando 5 tareas seguidas terminan así, el agente deja de llamar durante 5 minutos, para que una caída del proveedor no gaste el tiempo del worker en llamadas que no pueden salir bien; las tareas siguen en cola.

Un análisis fallido se intenta de nuevo solo cuando el problema crece o vuelve, y de inmediato cuando lo pides: `POST /v1/problems/{problem}/analyze`.

### Tu receptor de webhooks está caído

La alerta existe antes de intentar cualquier entrega: es una fila, se ve en la Consola y la devuelve `GET /v1/alerts`. La entrega es una segunda fila con sus propios intentos (salto 9). Un receptor que estuvo caído un día recibe la alerta en el séptimo intento, con el mismo id de evento, así que puede ignorar lo que ya manejó. Un receptor que estuvo caído más tiempo lee lo que se perdió con `GET /v1/alerts`, o pide de nuevo entregas sueltas.

### Un despliegue en mitad de una corrida

| Forma            | Qué hace un despliegue                                                                                                                      | Por qué no se rompe nada                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Un proceso       | `SIGTERM`: las solicitudes tienen 20 segundos, los segmentos abiertos se escriben, la pasada termina su paso actual y luego el proceso sale | Un paso que se cortó es una reserva que vence o una transacción que nunca confirmó. El proceso nuevo lo hace otra vez |
| Funciones de AWS | Las llamadas en curso terminan en la versión vieja; las nuevas empiezan en la nueva                                                         | Lo mismo, y la cola conserva lo que una llamada interrumpida no borró                                                 |
| Las dos          | La versión vieja y la nueva corren juntas un momento                                                                                        | Las migraciones solo agregan: un binario más viejo sigue funcionando contra un esquema más nuevo                      |

Un worker al que matan en mitad de una consolidación deja su hora marcada `running`. Otro worker toma esa hora a los 20 minutos. Es el único caso en que los números pueden tardar más de 10 minutos; los problemas no se afectan, porque la reserva de un segmento es de 2 minutos.

### La misma corrida empieza dos veces

Pasa: una programación que entrega la misma marca dos veces, dos workers, el reintento de una llamada que en realidad sí había terminado bien. Cada trabajo tiene un reclamo que solo una corrida puede ganar:

| Trabajo                             | El reclamo                                                                                                     |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Revisar un segmento                 | La reserva: `FOR UPDATE SKIP LOCKED`                                                                           |
| Sumar los contadores de un segmento | `UPDATE segments SET rolled_at … WHERE rolled_at IS NULL`; si la cuenta queda corta, la transacción se deshace |
| Los números de una hora             | Se reemplazan enteros; dos corridas escriben las mismas filas                                                  |
| Una tarea del agente                | El reclamo de la [tabla de tareas](#trabajo-como-filas); una tarea abierta por problema                        |
| Liberar una alerta                  | `UPDATE … WHERE released_at IS NULL`                                                                           |
| Una entrega de webhook              | La reserva de la fila de la entrega; tu receptor ve el mismo id `evt_…` si un intento se repite                |
| La tarea diaria                     | Una fila de tarea por proyecto y día                                                                           |

### Relojes que no coinciden

| Reloj                              | Dónde está mal                                                    | Qué hace el motor                                                                                                                                                                                                               |
| ---------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Un dispositivo                     | `ts` en el pasado o en el futuro                                  | Cada lote trae `sent_at`. Cuando difiere de la hora de llegada en más de 2 minutos, las horas del lote se corren esa diferencia para ordenar. Un evento de más de 7 días se descarta como `too_old` y se cuenta en la respuesta |
| Un proceso del motor               | Su hora difiere de la de la base de datos                         | Las reservas, `release_by` y todo «¿ya toca?» usan el reloj de la **base de datos** (`now()` en la sentencia), no el del proceso. `sypnia doctor` falla su revisión `clock` por encima de 5 segundos de diferencia              |
| Un proceso de ingesta, por minutos | Un segmento queda nombrado dentro de una hora que ya está cerrada | El registro tiene un segmento de una hora cerrada sin consolidar; la consolidación vuelve a abrir esa hora. Las horas cuentan por llegada, así que nada se pierde ni se duplica                                                 |

### La cola se atrasa

En AWS, un worker más lento que lo que llega se nota en la cola de entrada antes que en cualquier otra parte. Mientras dura no se pierde nada: la cola guarda un mensaje 4 días. Crecen dos cosas, y las dos se vigilan: la antigüedad del mensaje más viejo (una alarma a los 2 minutos) y el atraso del propio motor (una alerta `engine.failing` a los 30 minutos). Los SDK no notan nada, porque la Ingesta responde apenas el lote está en la cola. Lo primero que hay que subir es el número de copias de la función worker.

## Colas y colas de mensajes fallidos

### En AWS: una cola y su cola de mensajes fallidos

La cola de entrada ocupa el lugar que el búfer en memoria tiene en la otra forma. Es la única cola del motor; por qué hay una y no cuatro está en [Formas de despliegue](https://docs.sypnia.com/es/architecture/deployment-shapes#por-qu%C3%A9-una-cola-y-solo-una). La plantilla la crea con estos valores, y la razón de cada uno:

| Ajuste                                         | Valor                                     | Por qué                                                                                                    |
| ---------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Tipo                                           | Estándar                                  | El orden no importa y un duplicado no hace daño: `batch_id`                                                |
| Un mensaje                                     | Un lote validado, en gzip, máximo 256 KiB | Un lote más grande lo escribe la Ingesta en el Bucket y el mensaje solo lo nombra                          |
| Retención de mensajes                          | 4 días                                    | Un worker puede estar roto un fin de semana largo sin que se pierda nada                                   |
| Ventana de agrupación                          | 10 segundos, o 500 mensajes, o 6 MB       | Los segmentos siguen siendo pocos; una falla espera aquí máximo 10 segundos                                |
| Tiempo de invisibilidad                        | 15 minutos                                | No puede ser menor que el tiempo límite del worker. El worker mismo lo acorta para un mensaje que devuelve |
| Entregas antes de la cola de mensajes fallidos | 5 (`maxReceiveCount`)                     | Con las esperas de abajo, unos 20 minutos intentando                                                       |
| Retención de la cola de mensajes fallidos      | 14 días, contados desde el primer envío   | Tiempo para mirar, corregir y hacer redrive                                                                |
| Cifrado                                        | En reposo, con las llaves del servicio    | Los mensajes llevan datos de eventos                                                                       |

**Figura (diagrama aún sin dibujar)**: La vida de un mensaje. Entregado, escrito y borrado es el camino normal. Un mensaje que falla vuelve tras esperas crecientes; después de cinco entregas queda estacionado en la cola de mensajes fallidos hasta que alguien hace redrive.

Mostrará: DIAGRAMA DE ESTADOS Y TIEMPO de UN mensaje por la cola de entrada, de izquierda a derecha. Nodo inicial «Ingesta: SendMessage ok → 200 al SDK». Luego una pista horizontal con el rótulo «Cola de entrada», con el mensaje dibujado como un sobre pequeño que avanza por estas estaciones, cada una una caja redondeada con rótulos exactos: (1) «Esperando · visible» → flecha «se entrega con hasta 10 s de otros mensajes» → (2) «En curso · invisible, lo tiene el worker». De (2) salen TRES ramas. RAMA A (color de acento, el camino feliz) → «Segmento escrito + fila del registro» → «Borrado» (fin, marca de visto). RAMA B (tono de advertencia) con el rótulo «el worker lo reporta como fallido» → una caja «Visible de nuevo tras la espera» con una tabla pequeña adentro: «entrega 1 → 15 s», «2 → 1 min», «3 → 5 min», «4 → 15 min» → flecha de regreso a la estación (1), con el rótulo «se entrega de nuevo: conteo de entregas +1». RAMA C (punteada) con el rótulo «al worker lo mataron: no hay respuesta» → «Visible de nuevo a los 15 min (tiempo de invisibilidad)» → de regreso a la estación (1). De la estación (1), una flecha punteada hacia abajo con el rótulo «el conteo de entregas pasaría de 5» hacia una segunda pista debajo con el rótulo «Cola de mensajes fallidos · se guarda 14 días», donde el sobre queda en una caja «Estacionado · alarma: DeadLetterNotEmpty». De esa caja, una flecha curva de regreso HACIA ARRIBA a la estación (1) de la cola de entrada con el rótulo «redrive: aws sqs start-message-move-task» y la nota «llega como mensaje nuevo; los duplicados se saltan por batch_id». El elemento encendido es la pista de mensajes fallidos y su flecha de redrive. Bajo todo el diagrama, una regla de tiempo delgada para la rama B: «0 · 15 s · 1 min 15 s · 6 min 15 s · 21 min 15 s → cola de mensajes fallidos». Llamadas numeradas (1) esperando, (2) en curso, (3) borrado, (4) la tabla de esperas, (5) cola de mensajes fallidos, (6) redrive.

**Qué le dice el worker a la cola.** Una entrega trae muchos mensajes. El worker escribe sus segmentos y sus filas del registro, y luego responde con los ids de los mensajes que no pudo terminar. Solo esos vuelven. Fíjate en que un error nunca se escapa del manejador: un manejador que falla entero devolvería los mensajes buenos junto con el malo.

`crates/sypnia/src/lambda.rs`

```rust
/// El caso de la cola en `worker_event`. La respuesta nombra los mensajes que hay que entregar de nuevo.
async fn intake_batch(engine: &Engine, batch: SqsEvent) -> SqsBatchResponse {
    let mut failed = Vec::new();
    // Un grupo por proyecto y entorno: los mensajes que van a compartir un segmento.
    for group in intake::group(batch.records) {
        match intake::write_segment(engine, &group).await {
            // El objeto existe y su fila del registro también. Revisar puede fallar: la pasada lo recoge.
            Ok(segment) => {
                let _ = fast_path::scan(engine, std::slice::from_ref(&segment)).await;
            }
            Err(error) => {
                tracing::warn!(%error, scope = %group.scope, "segment not written; messages go back");
                for message in &group.messages {
                    // 15 s, 1 min, 5 min, 15 min, según cuántas veces se entregó.
                    queue::delay(engine, message, redelivery_wait(message.receive_count)).await;
                    failed.push(BatchItemFailure { item_identifier: message.id.clone() });
                }
            }
        }
    }
    SqsBatchResponse { batch_item_failures: failed }
}
```

Un mensaje que el worker devuelve se ve de nuevo después de su espera. Un mensaje a cuyo worker lo mataron, por memoria o por tiempo, se ve de nuevo cuando termina el tiempo de invisibilidad: hasta 15 minutos después. Esos eventos llegan tarde, no se pierden, y son el único caso en AWS en que un problema puede no cumplir sus 2 minutos sin que nada esté roto de forma permanente.

#### Redrive

Los mensajes de la cola de mensajes fallidos se quedan ahí 14 días. Nada los lee por su cuenta: un lote que no se pudo escribir cinco veces es un error que hay que mirar o una caída que hay que esperar, y a ninguno de los dos lo ayuda un sexto intento inmediato. Cuando la causa ya no esté, devuélvelos:

```bash
# Cuántos hay estacionados
aws sqs get-queue-attributes --queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
  --attribute-names ApproximateNumberOfMessages

# Mirar uno sin quitarlo
aws sqs receive-message --queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
  --max-number-of-messages 1 --visibility-timeout 0

# Devolverlos todos a la cola de entrada
aws sqs start-message-move-task --source-arn "$(aws sqs get-queue-attributes \
  --queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
  --attribute-names QueueArn --query Attributes.QueueArn --output text)"
```

Los mensajes devueltos llegan como nuevos y siguen el camino normal. Si algunos en realidad ya se habían escrito, sus ids de lote ya se conocen y sus líneas se saltan.

#### Alarmas

La plantilla crea tres alarmas. Son alarmas de CloudWatch porque deben funcionar cuando el motor mismo no funciona; apúntalas a una notificación tuya.

| Alarma               | Se dispara cuando                                                                                | Quiere decir                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `DeadLetterNotEmpty` | La cola de mensajes fallidos tiene al menos 1 mensaje, durante 1 minuto                          | Se apartaron lotes. Mira uno, corrige, haz redrive                              |
| `IntakeBacklog`      | El mensaje más viejo de la cola de entrada tiene más de 120 segundos, durante 3 minutos seguidos | El worker no da abasto, o no está corriendo                                     |
| `WorkerFailing`      | La función worker terminó en error en 3 de los últimos 5 minutos                                 | Un error de código, un permiso que falta, Postgres o el Bucket fuera de alcance |

### En un solo proceso: el búfer

`sypnia serve` no tiene cola, porque no la necesita: el proceso es la memoria.

|                                              |                                                                                                                                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dónde espera un lote                         | En el segmento abierto de su proyecto, en memoria, máximo 2 segundos                                                                                                                        |
| Cuándo se le responde al SDK                 | Después de que el segmento está en el Bucket. No antes                                                                                                                                      |
| Qué pierde una caída del proceso             | Nada de lo que se respondió con `200`. Los lotes de los segmentos abiertos, máximo 2 segundos de tráfico, no habían sido respondidos: sus SDK reciben un error de red y los envían de nuevo |
| Qué puede costar igual una caída             | Esos mismos lotes, si el proceso sigue caído más tiempo del que los SDK pueden guardarlos (salto 1)                                                                                         |
| Una fila del registro que aún no se escribió | Se encuentra de nuevo listando: al arrancar, un worker lista las últimas dos horas de cada proyecto y agrega lo que el registro no conoce. La tarea diaria revisa también el día anterior   |
| Una parada ordenada                          | Los segmentos abiertos se escriben antes de que el proceso salga                                                                                                                            |

Esta es la diferencia honesta entre las dos formas. En AWS el punto durable es la cola, un servicio administrado que sigue funcionando mientras las funciones fallan. En un solo proceso el punto durable es el Bucket, y entre el SDK y el Bucket hay un proceso y 2 segundos. Corre dos procesos `ingest` detrás de un balanceador si esos segundos te importan: el reintento de un SDK llega entonces al otro.

### Trabajo como filas

Todo lo que debe pasar más tarde, después del Bucket, es una fila en Postgres con una hora, no un mensaje en una cola. Tres clases de trabajo usan el patrón:

| Trabajo                                                            | Tabla                                             | Intentos y esperas                        | Abandonado                      | Se ve en                                                                     | Se vuelve a procesar con                                        |
| ------------------------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| El análisis del agente, la tarea diaria, las sugerencias semanales | `jobs`                                            | 3: a los 5 s y a los 30 s                 | `status = 'dead'`, `last_error` | El problema: `analysis.status: failed`. `GET /v1/engine/status`: `jobs.dead` | `POST /v1/problems/{problem}/analyze`                           |
| Liberar una alerta                                                 | `alerts` (`release_by`, `released_at`)            | Cada pasada, hasta que se hace            | Nunca                           | `GET /v1/alerts`                                                             | —                                                               |
| Una entrega de webhook                                             | `webhook_deliveries`                              | 7: a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h | `status = 'failed'`, `error`    | `GET /v1/webhooks/{id}/deliveries?status=failed`                             | `POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry` |
| Una hora por consolidar de nuevo                                   | `hours` (`status`, `attempts`, `next_attempt_at`) | Siguiente pasada, luego 1, 5, 15, 30 min  | Nunca dentro de 48 horas        | `GET /v1/engine/status`: `hours.failed`                                      | `sypnia aggregate --from … --to …`                              |

Por qué filas y no más colas:

- **La fila se escribe en la transacción que la causa.** Un problema nace y su tarea existe, o ninguna de las dos cosas. Un mensaje de cola enviado después de un commit se puede perder entre los dos; uno enviado antes puede anunciar un trabajo que se deshizo.
- **Una fila se puede leer.** «¿Qué está esperando, desde cuándo, cuántas veces se intentó, qué dijo?» es una consulta, y la API la responde. Una cola solo se puede contar.
- **Nada más que desplegar.** La forma de un solo proceso no tiene ningún servicio de colas, y el mismo código corre en las dos.

La tabla y el reclamo. Fíjate en la segunda condición del reclamo: una tarea `running` cuya reserva venció era de un worker que murió, y otro la toma.

`migrations/0006_jobs.sql`

```sql
CREATE TABLE jobs (
    id              text PRIMARY KEY,                    -- job_…
    project_id      text NOT NULL REFERENCES projects ON DELETE CASCADE,
    kind            text NOT NULL CHECK (kind IN ('analysis', 'daily', 'suggestions')),
    subject         text NOT NULL,                       -- el id del problema, el día, la semana
    status          text NOT NULL DEFAULT 'queued'
                    CHECK (status IN ('queued', 'running', 'done', 'dead')),
    again           boolean NOT NULL DEFAULT false,      -- llegó un disparador mientras corría: correr una vez más
    attempts        integer NOT NULL DEFAULT 0,
    next_attempt_at timestamptz NOT NULL DEFAULT now(),
    leased_until    timestamptz,
    last_error      text,
    created_at      timestamptz NOT NULL DEFAULT now(),
    finished_at     timestamptz
);
-- Una tarea abierta por sujeto: un segundo disparador enciende `again` en vez de insertar.
CREATE UNIQUE INDEX jobs_one_open ON jobs (project_id, kind, subject)
    WHERE status IN ('queued', 'running');
CREATE INDEX jobs_due ON jobs (next_attempt_at) WHERE status = 'queued';
```

`crates/sypnia-db/sql/job_claim.sql`

```sql
-- $1 = clase, $2 = la reserva. Devuelve una tarea, o ninguna.
UPDATE jobs j
   SET status = 'running', attempts = j.attempts + 1, leased_until = now() + $2
 WHERE j.id = (
        SELECT id FROM jobs
         WHERE kind = $1
           AND ((status = 'queued'  AND next_attempt_at <= now())
             OR (status = 'running' AND leased_until < now()))   -- su worker murió
         ORDER BY next_attempt_at
         LIMIT 1
           FOR UPDATE SKIP LOCKED)
RETURNING j.*;
```

Una tarea que falla vuelve a `queued` con un `next_attempt_at` posterior, o pasa a `dead` en su tercera falla. En AWS el worker se llama a sí mismo para correr una tarea de inmediato; esa llamada es solo un atajo. Si se pierde, la marca del minuto encuentra la fila. Los reintentos propios de Lambda para esa llamada están apagados, porque la fila es el reintento.

## Salud

Tres cosas responden «¿está funcionando?», de la más barata a la más completa.

### `GET /healthz`

Pública, sin credencial. Responde `200` cuando el proceso está arriba y atendiendo, y a propósito no prueba Postgres ni el Bucket: una caída de la base de datos no debe sacar a la Ingesta de un balanceador, porque la Ingesta funciona sin la base de datos.

```json
{ "status": "ok", "version": "1.0.0", "role": "all" }
```

Vigílala desde fuera de la máquina donde corre el motor. Un motor caído no puede levantar su propia alerta.

### `GET /v1/engine/status`

Con el token raíz **\[Motor]**. El estado del procesamiento, de todos los proyectos. Es lo que imprime la revisión `pipeline` de `sypnia doctor` y con lo que se decide la alerta `engine.failing`.

```json
{
  "state": "ok",
  "engine_version": "1.0.0",
  "last_pass_at": "2026-03-12T10:34:10Z",
  "lag_seconds": 21,
  "rollup_lag_seconds": 190,
  "segments": { "unscanned": 2, "unrolled": 5, "quarantined": 0 },
  "hours": { "failed": 0 },
  "jobs": { "queued": 1, "running": 1, "dead": 0 },
  "alerts": { "held": 1 },
  "webhook_deliveries": { "pending": 0, "failed": 0 },
  "queue": { "waiting": 0, "oldest_seconds": 0, "dead_letter": 0 }
}
```

| Campo                | Significado                                                                                                                                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lag_seconds`        | **El número de frescura.** La antigüedad del segmento más viejo que la vía rápida no ha revisado y que no está en cuarentena. En AWS, la antigüedad del mensaje más viejo de la cola de entrada cuando ese es más viejo. `0` cuando nada espera                                             |
| `rollup_lag_seconds` | La antigüedad del segmento más viejo que la consolidación aún no ha sumado                                                                                                                                                                                                                  |
| `state`              | `ok`: `lag_seconds` por debajo de 120 y `rollup_lag_seconds` por debajo de 600, las dos promesas. `behind`: por encima de cualquiera. `failing`: `lag_seconds` por encima de 1.800, o algo en cuarentena, una hora fallida durante 30 minutos, o un mensaje en la cola de mensajes fallidos |
| `queue`              | La cola de entrada. `null` en la forma de un solo proceso                                                                                                                                                                                                                                   |

Por proyecto, la misma idea es `data_through` en [`GET /v1/summary`](https://docs.sypnia.com/es/api/overview-and-authentication), que cualquier token `read` puede llamar y que Sypnia Cloud muestra en la app **\[Nube]**.

**El objetivo de frescura.** `lag_seconds` por debajo de 120 y `rollup_lag_seconds` por debajo de 600. El motor mide los dos en cada pasada y los escribe en su log; cuando cualquiera se queda por encima de 1.800 segundos crea la alerta `engine.failing`, que va a tu webhook como cualquier otra. El objetivo es una regla de diseño, verificada por las pruebas. Un porcentaje medido se publicará aquí cuando el motor haya corrido con volumen.

### `sypnia doctor`

`doctor` prueba aquello de lo que depende el motor, una línea por cosa. Dos de sus revisiones son sobre esta página:

```text
config    ok    14 settings read, 0 unknown
database  ok    postgres 16.4, schema 12 (up to date), 3 ms
storage   ok    s3://sypnia-shop: put, get, delete, presign
address   ok    https://sypnia.example.com/healthz answered 200
pipeline  ok    last pass 12 s ago, lag 21 s, 0 quarantined, 0 failed hours, 0 dead jobs
queue     ok    intake 0 waiting, dead-letter 0
ai        ok    openrouter, model <model>: answered in 0.9 s
webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock     ok    0.2 s from the database's clock
all checks passed
```

| Revisión   | Falla cuando                                                                                                                                    | Imprime                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `pipeline` | Ninguna pasada terminó en los últimos 3 minutos; `lag_seconds` por encima de 120; un segmento en cuarentena; una hora fallida; una tarea `dead` | Cada segmento en cuarentena con su error, y la línea de `sypnia aggregate` que lo vuelve a procesar |
| `queue`    | La cola de entrada o su cola de mensajes fallidos no se pueden leer; la cola de mensajes fallidos no está vacía                                 | Cuántos mensajes hay estacionados, y el comando de redrive. Se omite en la forma de un solo proceso |
| `clock`    | El reloj de la máquina está a más de 5 segundos del de la base de datos                                                                         | Las dos horas                                                                                       |

Un número más es un número de salud y no solo una línea de log: **problemas traducidos con source maps ÷ problemas que tenían versión y pila**, en 24 horas. El sistema del que sale este motor pasó una vez seis días sin traducir nada y nadie lo notó. `doctor` lo imprime, y [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping#traducci%C3%B3n-con-source-maps) lo explica.

## Lo que no prometemos

- **Los eventos que el motor nunca aceptó.** Mientras la Ingesta no responde, un SDK guarda 500 eventos y reintenta; una pestaña que se cierra se lleva su cola; el último lote de una página, enviado cuando la página se oculta, se envía una sola vez. Un SDK de servidor reintenta y luego descarta. No hay almacenamiento en el dispositivo.
- **Entrega exactamente una vez de un webhook.** Es al menos una vez. Tu receptor recibe otra vez el mismo id `evt_…` cuando un intento se repite; ignora un id que ya manejaste.
- **Los 2 minutos durante una caída.** Las promesas de frescura valen mientras las piezas del motor están arriba. Durante una falla y justo después, los datos llegan tarde, tanto como duró la falla más lo que tarde en ponerse al día. No se pierden y no quedan mal.
- **Los 2 minutos para un lote a cuyo worker lo mataron** (AWS). Se entrega de nuevo cuando termina su tiempo de invisibilidad, hasta 15 minutos después.
- **Los 10 minutos para una hora a cuyo worker lo mataron a mitad de la corrida.** Otro worker toma la hora a los 20 minutos.
- **Lo que escribió la gente, sin un respaldo de Postgres.** Los estados, notas, reglas, llaves y tokens solo existen ahí. Los números y los problemas se pueden reconstruir desde el Bucket mientras la retención conserve los segmentos; más viejos que eso, no.
- **Los eventos de un segmento en cuarentena,** hasta que alguien lo vuelva a procesar. Están a salvo en el Bucket y no están en ningún conteo.
- **El orden entre eventos de lotes distintos.** Las líneas de tiempo se ordenan por la hora de los propios eventos, corregida por el reloj del dispositivo. Dos eventos separados por unos milisegundos en dos dispositivos pueden aparecer en cualquier orden.
- **Una alarma cuando todo está caído** en la forma de un solo proceso. Si el único proceso se detiene, nada dentro de él te puede avisar. Vigila `/healthz` desde otro lado.
- **Un límite a la caída de otro.** Si tu proveedor de bucket o tu Postgres pierde datos que había confirmado, el motor no los puede devolver.

## Qué cambió frente al sistema del que sale

| Allá                                                                                                             | Aquí                                                                                                                             | Por qué                                                       |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Un flujo de entrega administrado; un registro que fallaba se escribía bajo un prefijo de errores y nadie lo leía | Una cola con cola de mensajes fallidos, una alarma y un comando de redrive                                                       | Lo que se aparta debe ser visible y poderse volver a procesar |
| Una hora que fallaba dos veces no se volvía a intentar                                                           | Se intenta en la siguiente pasada, luego con esperas crecientes, durante 48 horas; una alerta a los 30 minutos                   | El incidente del 2026-09-30                                   |
| Una línea corrupta se volvía una fila de valores vacíos                                                          | Una línea que no se puede interpretar se cuenta y se salta; un segmento que no se puede leer queda en cuarentena tras 5 intentos | Una entrada mala solo debe costarse a sí misma                |
| Una tarea para una sola app: nadie con quien ser justo                                                           | Turnos por proyecto en la vía rápida, un presupuesto de memoria por corrida, una parte del búfer                                 | Muchos proyectos comparten un motor                           |
| La salud era una línea de log                                                                                    | `/healthz`, `/v1/engine/status`, `sypnia doctor`, la alerta `engine.failing`                                                     | Seis días sin traducir pilas, sin que nadie lo notara         |

## Sigue
