# Flujo de datos

> Cada salto que da un evento dentro del motor, con su presupuesto de tiempo, qué espera a qué, cómo frena el motor, qué pasa cuando una pieza se cae y cómo se cumplen las promesas de 2 y 10 minutos.

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

Esta página sigue un evento por el motor, salto por salto, y le pone un número a cada uno. Es para quien opera el motor y para quien quiera comprobar que las promesas de frescura son aritmética y no esperanza.

Las promesas, de [Cómo funciona](https://docs.sypnia.com/es/start/how-it-works):

- un problema nuevo aparece, y puede alertar, **en menos de 2 minutos** desde su primer evento;
- los conteos, los números de rendimiento y la lista de sesiones están completos **en 10 minutos**;
- una grabación se puede ver cuando su sesión lleva 2 minutos inactiva, o terminó.

> **Nota: Sobre los números y el código**
>
> Cada tiempo de esta página es un **presupuesto**: lo máximo que un salto puede tardar, y lo que las pruebas exigen. Ninguno es una medición del motor en Rust, que todavía no existe. Las cifras tomadas del sistema del que sale este motor lo dicen. El Rust es un extracto de diseño; el repositorio se abre al lanzar.

## Los saltos

**Figura**: Los saltos y sus presupuestos. Sobre la línea el SDK está esperando; debajo, nadie. El Bucket es el punto donde un evento queda a salvo.

1. Tu app envía un lote a la Ingesta, máximo cada 10 segundos.
2. La Ingesta escribe un segmento en el Bucket, y luego responde `200` con lo que aceptó y lo que descartó.
3. La Ingesta escribe la fila del registro del segmento en Postgres, después de responder.
4. La Vía rápida lee los segmentos nuevos cada 30 segundos.
5. Escribe el problema en Postgres y retiene su alerta.
6. El agente toma la tarea y escribe la frase.
7. Postgres libera la alerta hacia Alertas.
8. La Consolidación lee la hora abierta cada 5 minutos y escribe números y sesiones.
9. La API lee Postgres; el servidor MCP y la Consola leen a través de la API.

| # | Salto                                 | Qué pasa                                                                                                                                      | Presupuesto                                                   | ¿Síncrono?                               |
| - | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| 1 | Tu app (SDK) → Ingesta                | El SDK del navegador envía cada 10 s, a los 50 eventos o cuando la página se oculta. Los SDK de servidor envían cuando termina una solicitud. | 10 s                                                          | —                                        |
| 2 | Ingesta → Bucket                      | Llave, origen, tamaños, cada evento; las líneas esperan en un búfer y se escriben como un segmento.                                           | 2 s en el búfer, 300 ms para la escritura                     | Sí: la respuesta espera al objeto        |
| 3 | Ingesta → Postgres                    | Una fila del registro que dice «este segmento existe».                                                                                        | 50 ms                                                         | No: después de responder, con reintentos |
| 4 | Bucket → Vía rápida                   | El worker toma los segmentos que nadie revisó. En un solo proceso se despierta apenas cae un segmento.                                        | 30 s (`processing.interval_seconds`)                          | No                                       |
| 5 | Vía rápida → Postgres                 | Leer el segmento, quedarse con las fallas, hacer upsert de problemas, registrar la alerta. Una transacción.                                   | 5 s                                                           | No                                       |
| 6 | El agente                             | Traducir la pila con source maps, armar el contexto, llamar al modelo, revisar la respuesta.                                                  | 60 s (`ai.timeout_seconds`), menos si la alerta ya debe salir | No                                       |
| 7 | Alertas                               | Liberar la alerta: marcarla, enviar el webhook.                                                                                               | 10 s por entrega (`webhooks.timeout_seconds`)                 | No                                       |
| 8 | Bucket → Consolidación → Postgres     | Releer la hora abierta, reemplazar sus números, sumar a los contadores, escribir archivos por sesión.                                         | Empieza cada 5 min; 60 s por proyecto y hora                  | No                                       |
| 9 | Postgres → API, servidor MCP, Consola | Lecturas con índice. Los fragmentos de grabación y las trazas se traen del Bucket.                                                            | 300 ms para una lista                                         | Sí, para quien lee                       |

Solo el salto 2 hace esperar a alguien, y hace esperar al SDK a propósito: la respuesta `200` significa que los eventos están en el Bucket, no en la memoria de un proceso que puede morir. Todo lo que sigue puede fallar y volver a correr sin perder un evento, porque el segmento sigue ahí.

## Qué es síncrono

**Figura**: El único tramo síncrono. La respuesta sale después de que el objeto existe y antes de escribir nada en Postgres.

1. Tu app envía un lote: `POST /v1/ingest/events` con un `batch_id` y 6 eventos.
2. Ingesta encuentra el proyecto en su caché de llaves y revisa el origen, los tamaños y cada evento. Sin consulta a la base de datos.
3. Agrega las líneas al búfer. El búfer espera máximo 2 segundos y se comparte con los otros lotes del proyecto.
4. Ingesta escribe el búfer en el Bucket como un solo segmento.
5. El Bucket confirma que el objeto existe.
6. Solo entonces Ingesta responde `200` con `accepted: 6, dropped: 0`.
7. Después de responder, Ingesta escribe en Postgres la fila de registro del segmento, y reintenta hasta lograrlo.

Un diagrama de secuencia con cuatro líneas de vida y el tiempo hacia abajo: Tu app (SDK), Ingesta, Bucket y Postgres. El SDK espera desde el mensaje 1 hasta el 6; en el mensaje 7 ya se fue. Hay dos finales alternos, cada uno junto al paso que reemplaza: si el búfer está lleno, Ingesta responde `503` con `Retry-After`; si el Bucket rechaza la escritura, Ingesta responde `503 unavailable` y el SDK reenvía el mismo `batch_id` tras 1 s, 4 s y 15 s.

Vale la pena notar tres cosas en la figura.

- **La respuesta es honesta.** `accepted` cuenta eventos que ya están en un objeto. Si el Bucket rechaza la escritura, el SDK recibe `503 unavailable` y envía el mismo lote otra vez con el mismo `batch_id`.
- **El búfer es compartido.** Todos los lotes de un proyecto y entorno que llegan dentro de los mismos 2 segundos salen en un solo objeto. Un proyecto con mucho tráfico escribe como máximo 30 objetos por minuto, sin importar cuántos navegadores envíen.
- **Postgres no está en el camino.** La fila del registro se escribe después de responder. Si Postgres está caído, la ingesta sigue aceptando y la fila se escribe más tarde.

En AWS una función no puede guardar un búfer entre solicitudes, así que el búfer es una cola: la ingesta responde cuando el lote está en la cola, y el worker escribe el segmento. El contrato es el mismo; el punto donde el dato queda a salvo pasa del Bucket a la cola por unos segundos. Mira [Formas de despliegue](https://docs.sypnia.com/es/architecture/deployment-shapes).

## Dos relojes

El motor lee los mismos segmentos dos veces, a dos velocidades, para dos trabajos distintos.

**Figura**: Dos relojes sobre los mismos archivos. La vía rápida responde «¿se rompió algo nuevo?» cada 30 segundos. La consolidación responde «¿cuánto hubo de todo?» cada 5 minutos.

Una línea de tiempo de 09:10 a 09:25 con tres filas. Arriba, los segmentos en el Bucket: los archivos llegan en momentos irregulares; el que se escribió a las 09:12:16 contiene el pago fallido. En el medio, la Vía rápida: una marca cada 30 segundos; la de las 09:12:30 revisa el segmento de las 09:12:16 y encuentra un problema nuevo, y entre la primera falla (09:12:04) y el problema (09:13:02) pasan 58 segundos, con un presupuesto de 120. Abajo, la Consolidación: una corrida a las 09:15, 09:20 y 09:25, y cada una relee toda la hora 09; el segmento del pago fallido se cuenta en la corrida de las 09:15, 2 minutos y 56 segundos después, con un presupuesto de 10 minutos. La Vía rápida escribe problemas, sus ocurrencias y a quién afectaron. La Consolidación escribe números de páginas y API, sesiones, clics, el índice de trazas y el uso.

|               | Vía rápida                                                  | Consolidación                                                                        |
| ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Pregunta      | ¿Se rompió algo nuevo, y a quién le pasó?                   | ¿Cuánto pasó de todo?                                                                |
| Lee           | Cada segmento nuevo, una vez                                | Toda la hora abierta, de nuevo, en cada corrida                                      |
| Se queda con  | Solo fallas: errores, llamadas fallidas, tiempos agotados   | Todos los eventos                                                                    |
| Escribe       | `problems`, `problem_occurrences`, `problem_hits`, `alerts` | Números por hora y por día, `sessions`, `traces`, `usage_daily`, archivos por sesión |
| Cada          | 30 s                                                        | 5 min                                                                                |
| Nunca escribe | Un número de la consolidación                               | Un problema                                                                          |

Dividir por tabla es lo que mantiene simples a las dos. Ninguna actualiza una fila que es de la otra, así que no hay nada que reconciliar entre ellas.

Esta es la vía rápida. Fíjate en el préstamo: un segmento se reserva por 2 minutos con una sola sentencia, se lee sin dejar una transacción abierta, y se marca como revisado en la misma transacción que escribe sus problemas.

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

```rust
pub async fn run(engine: &Engine) -> Result<FastPathReport, EngineError> {
    let mut report = FastPathReport::default();
    held::promote_due(engine, &mut report).await?; // llamadas del navegador que esperaban su mitad del servidor

    // UPDATE … WHERE key = (SELECT … FOR UPDATE SKIP LOCKED LIMIT 1) RETURNING …
    // Dos workers nunca reciben el mismo segmento; el préstamo de un worker caído se vence.
    while let Some(segment) = engine.db.lease_unscanned_segment(LEASE).await? {
        let scope = segment.scope();
        let mut failures = FailureFold::new(&scope);

        let mut lines = engine.store.read_lines(&segment.key).await?;
        while let Some(line) = lines.try_next().await? {
            // Una línea que no se puede leer se cuenta y se salta. Nunca detiene el segmento.
            let Ok(record) = serde_json::from_slice::<Record>(&line) else {
                report.unreadable += 1;
                continue;
            };
            if let Some(failure) = Failure::from_record(&record) {
                failures.push(failure);
            }
        }

        let mut tx = engine.db.begin().await?;
        let fresh = tx.record_batches(&scope, &segment).await?; // los batch_id ya vistos se saltan
        let transitions = problems::apply(&mut tx, failures.only(&fresh)).await?;
        alerts::record(&mut tx, &transitions, engine.clock.now()).await?;
        tx.mark_scanned(&segment, fresh.skipped()).await?;
        tx.commit().await?; // problemas, alertas y registro avanzan juntos, o no avanzan

        agent::enqueue(engine, &transitions).await; // mejor esfuerzo; la siguiente pasada recoge lo que falte
        report.absorb(&segment, &transitions);
    }
    Ok(report)
}
```

## Cómo se cumplen los 2 minutos

El reloj arranca cuando la falla ocurre en tu app. El peor caso es la suma del peor caso de cada salto.

| Salto                                                                           | Un proceso (`serve`)                               | Funciones de AWS                                                                   |
| ------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| El SDK retiene el evento                                                        | 10 s                                               | 10 s                                                                               |
| Búfer o cola                                                                    | 2 s                                                | 10 s (la ventana de agrupación de la cola)                                         |
| Escritura del segmento                                                          | 0,3 s                                              | 0,3 s                                                                              |
| Espera de la vía rápida                                                         | 30 s (0 cuando ingesta y worker comparten proceso) | 0 s (la cola despierta al worker)                                                  |
| Revisión y transacción                                                          | 5 s                                                | 5 s                                                                                |
| **El problema existe**                                                          | **47,3 s**                                         | **25,3 s**                                                                         |
| Solo para una llamada del navegador que espera su mitad del servidor: retención | 15 s                                               | 15 s                                                                               |
| …y luego la siguiente pasada                                                    | 30 s                                               | 60 s (la programación de cada minuto, si ningún tráfico despierta antes al worker) |
| **El problema existe, caso retenido**                                           | **92,3 s**                                         | **100,3 s**                                                                        |

Las dos columnas terminan por debajo de 120 segundos. La retención se explica en [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping): una llamada fallida vista por el navegador espera hasta 15 segundos la falla que hay detrás en el servidor, para que una solicitud sea un solo problema. Solo aplica a proyectos que también envían datos del servidor.

**La alerta** se escribe en la misma transacción que el problema, retenida. La libera lo que ocurra primero:

1. el agente termina la frase;
2. pasan 100 segundos desde que la falla llegó a la ingesta (110 desde que ocurrió, contando los 10 del SDK).

Así, con un modelo configurado, el agente tiene lo que quede de esos 100 segundos, normalmente más de un minuto. Sin modelo, la alerta se libera de inmediato, con el título técnico. En el peor caso retenido en AWS no queda tiempo para el modelo, y la alerta sale con el título técnico; la frase aparece en el problema cuando se escribe.

Si subes `processing.interval_seconds` por encima de 30, la primera columna crece lo mismo, y el doble en el caso retenido. Con 60, el caso retenido pasa de 2 minutos. Por eso el ajuste llega hasta 60 y su descripción te lo advierte.

## Cómo se cumplen los 10 minutos

| Paso                                                                 | Peor caso      |
| -------------------------------------------------------------------- | -------------- |
| El SDK retiene el evento                                             | 10 s           |
| Búfer y escritura                                                    | 2,3 s          |
| Espera de la siguiente consolidación                                 | 5 min          |
| La consolidación de este proyecto y hora                             | 60 s           |
| **Números completos**                                                | **6 min 13 s** |
| Margen para una corrida que falla y se repite en la siguiente pasada | 3 min 47 s     |

Una consolidación que falla no se reintenta cinco minutos después. `rollup::is_due` es verdadero en cada marca de 5 minutos **y** siempre que la última corrida de un proyecto no haya terminado, así que el reintento llega con la siguiente pasada de 30 segundos.

Dos detalles mantienen bien los números al cambiar de hora:

- La hora de un segmento es la hora en que se **escribió**, no la que llevan sus eventos. Eventos enviados a las 09:59:58 pueden caer en la hora 10.
- Una hora se relee hasta 10 minutos después de terminar, y luego se cierra. No puede existir un segmento escrito en una hora cerrada, porque los segmentos se escriben con la hora actual.

### Grabaciones

Un fragmento de grabación no pasa por el búfer. Cada subida se escribe en el Bucket como su propio objeto antes de responder. La API lista los fragmentos de una sesión directamente del Bucket, así que una grabación se puede reproducir apenas existen sus fragmentos. El SDK sube el último fragmento cuando la página se oculta o la sesión queda inactiva; por eso la promesa dice «2 minutos inactiva, o terminada».

Un problema se enlaza con sus sesiones por `problem_hits`, que escribe la vía rápida. Por eso la grabación de la sesión detrás de un problema recién nacido se puede abrir desde la alerta, minutos antes de que esa sesión aparezca en la lista de sesiones.

## Contrapresión y la señal de «frena»

El motor nunca descarta en silencio. Cada tipo de presión tiene una respuesta, y el SDK sabe qué hacer con cada una.

| Presión                                                         | Dónde se nota                                            | El motor responde                                                                                            | El SDK hace                                                                                                     |
| --------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Demasiadas solicitudes desde una dirección con una llave        | Ingesta, un contador en memoria                          | `429 rate_limited` con `Retry-After`                                                                         | Espera y envía el mismo lote otra vez                                                                           |
| El búfer de un proyecto está lleno (32 MiB esperando escritura) | Ingesta                                                  | `503 unavailable` con `Retry-After: 2`                                                                       | Reintenta tras 1 s, 4 s y 15 s con el mismo `batch_id`; guarda máximo 500 eventos, los más viejos salen primero |
| El Bucket rechaza escrituras                                    | Ingesta                                                  | `503 unavailable`                                                                                            | Lo mismo                                                                                                        |
| El proyecto llegó a su límite de eventos                        | La respuesta de cada lote y de `/v1/ingest/config`       | `200` con `slow_down: { send: "failures" }`; los demás eventos se cuentan en `dropped_reasons.limit_reached` | Envía solo errores y solicitudes fallidas hasta `until`                                                         |
| El proyecto llegó a su límite de grabaciones                    | Lo mismo                                                 | `slow_down: { replay: false }`; los fragmentos reciben `429 limit_reached`                                   | Deja de grabar hasta `until`                                                                                    |
| El worker va atrasado                                           | El registro: segmentos sin revisar, horas sin consolidar | Nada cambia para los SDK. A los 30 minutos, una alerta `engine.failing`                                      | —                                                                                                               |
| Postgres no tiene conexiones libres                             | API                                                      | `503` con `Retry-After: 2`                                                                                   | Tu cliente reintenta                                                                                            |

El estado de «frena» se decide lejos de la solicitud. La consolidación cuenta el uso; una pasada lo compara con los límites y escribe el resultado en el proyecto; la ingesta lo lee de su caché. Fíjate en que la función de abajo es pura: los mismos contadores dan siempre la misma respuesta, así que es trivial de probar y segura de correr en cada pasada.

`crates/sypnia-core/src/quota.rs`

```rust
/// Lo que los SDK deben retener. `None` cuando el proyecto está dentro de sus límites,
/// que es siempre el caso cuando un límite es 0 (sin límite: el valor de un motor propio).
pub fn slow_down(usage: &Usage, limits: &Limits, period_end: DateTime<Utc>) -> Option<SlowDown> {
    let events_over = limits.events_per_month > 0 && usage.events >= limits.events_per_month;
    let replays_over = limits.replays_per_month > 0 && usage.replays >= limits.replays_per_month;

    match (events_over, replays_over) {
        (false, false) => None,
        (true, _) => Some(SlowDown {
            reason: SlowDownReason::EventsLimit,
            // Las fallas siempre se aceptan, así los problemas se siguen encontrando.
            send: Send::Failures,
            replay: false,
            until: period_end,
        }),
        (false, true) => Some(SlowDown {
            reason: SlowDownReason::ReplaysLimit,
            send: Send::All,
            replay: false,
            until: period_end,
        }),
    }
}
```

> **Advertencia: Cuánto puede pasarse un proyecto de su límite**
>
> El uso lo cuenta la consolidación y llega a la ingesta por una caché que se refresca cada 60 segundos. Así que un proyecto puede pasar un límite por lo que envíe en unos 7 minutos. La alternativa, contar en la solicitud, pondría una escritura a la base de datos en el camino caliente de cada lote. El motor elige llegar unos minutos tarde y nunca ser lento.

## Cuando una pieza se cae

| Caída                         | Qué sigue funcionando                                          | Qué se detiene                                                     | Qué se pierde                                                                    | Recuperación                                                                                                               |
| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Ingesta**                   | Leer: API, servidor MCP, Consola                               | Recibir                                                            | Los eventos que el SDK no alcance a guardar: conserva 500 y reintenta tres veces | No hace falta                                                                                                              |
| **Bucket**                    | Listas y problemas, desde Postgres                             | Recibir (`503`), grabaciones, líneas de tiempo de sesiones, trazas | Nada de lo aceptado; los SDK reintentan como arriba                              | No hace falta                                                                                                              |
| **Postgres**                  | Recibir: la ingesta usa su caché y sigue escribiendo segmentos | La vía rápida, la consolidación, la API (`503`), llaves nuevas     | Nada. Los segmentos esperan en el Bucket                                         | Se escriben las filas del registro que quedaron pendientes; luego el worker se pone al día, de lo más viejo a lo más nuevo |
| **El worker**                 | Recibir y leer                                                 | Problemas nuevos, números, alertas, chequeos de disponibilidad     | Nada                                                                             | Al arrancar revisa todo lo no revisado y consolida cada hora abierta de las últimas 48 horas                               |
| **El proveedor de IA**        | Todo lo demás                                                  | La frase                                                           | Nada. `analysis.status` queda en `failed` tras tres intentos                     | Se intenta de nuevo cuando el problema crece, o a pedido                                                                   |
| **El receptor de tu webhook** | Todo lo demás; las alertas se siguen registrando               | Esa entrega                                                        | Nada mientras duren los reintentos                                               | Las entregas se reintentan con esperas cada vez más largas; una alerta `engine.failing` si siguen fallando                 |

Dos reglas hacen corta esta tabla:

- **El Bucket es la fuente de la verdad.** Todo lo que hay en Postgres y viene de eventos se puede reconstruir desde los segmentos, con `sypnia aggregate --from … --to …`. Las excepciones son lo que escribieron las personas: estados, notas, reglas, llaves.
- **Una llave revocada sigue rechazada durante una caída de Postgres, y una llave válida sigue funcionando.** La caché conserva su última copia buena hasta una hora sin refrescarse. Después, la ingesta responde `503` en vez de adivinar.

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

| Allá                                                        | Aquí                                                     | Por qué                                                                                                                       |
| ----------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Una tarea cada hora, al minuto 20, hace todo                | Una vía rápida cada 30 s y una consolidación cada 5 min  | Las promesas de 2 y 10 minutos                                                                                                |
| Un búfer administrado de 60 s o 5 MB delante del bucket     | El búfer propio del motor, de 2 s o 4 MiB                | 60 s es la mitad del presupuesto de 2 minutos; y el despliegue propio no puede depender de un servicio que solo existe en AWS |
| La respuesta salía antes de confirmar la escritura          | La respuesta espera al objeto                            | Para que `accepted` sea verdad                                                                                                |
| Una hora fallida se reintentaba con una ventana de 48 horas | La misma ventana de 48 horas, más un reintento inmediato | Se conserva; fue lo que salvó horas allá                                                                                      |

## Sigue
