# El código

> El repositorio del motor, crate por crate, con los traits y tipos principales, las reglas que sigue cada línea de código, las pruebas que repiten horas grabadas, cómo correrlo en tu máquina y cómo fluye una contribución.

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

Esta página es un mapa del código fuente del motor, para quien quiera leerlo, correrlo o cambiarlo. Es la última de la sección a propósito: todo lo que nombra ya se explicó en una anterior.

> **Nota: El repositorio se abre al lanzar**
>
> El motor se escribe con la documentación primero. Esta página describe el repositorio como será cuando se abra: la disposición, los nombres y las reglas están decididos, y el código se escribe para coincidir con ellos. Los comandos y su salida son los que fija la [referencia de la CLI](https://docs.sypnia.com/es/cli/commands). Dónde vive el repositorio se publica al lanzar.

## El workspace

Un workspace de Cargo, once crates, un binario.

**Figura (diagrama aún sin dibujar)**: Los crates y de qué depende cada uno. Las partes del motor no se conocen entre sí; se encuentran en el binario.

Mostrará: El mismo grafo de dependencias en cuatro capas que la figura 1 de la página en inglés (architecture/codebase), con los mismos nodos (los nombres de los crates no se traducen), flechas, llamadas (1) a (4) y el mismo elemento encendido (el binario). Subrótulos traducidos: «sypnia (el binario)»: «CLI · serve · lambda · Engine»; «sypnia-ingest»: «puertas, búfer, OTLP»; «sypnia-pipeline»: «vía rápida, consolidación, sesiones, Parquet»; «sypnia-agent»: «contexto, proveedores, revisión, prompt»; «sypnia-alerts»: «reglas, liberación, webhook»; «sypnia-api»: «API HTTP, servidor MCP, Consola»; «sypnia-store»: «ObjectStore, llaves»; «sypnia-db»: «Database, migraciones, upserts»; «sypnia-fingerprint»: «hash64, marcos»; «sypnia-core»: «Event, ids, Scope, Histogram, puertos, errores · sin entrada ni salida»; «sypnia-testkit»: «horas grabadas, adaptadores en memoria, reloj fijo», nota «solo dependencia de desarrollo»; etiqueta de la flecha api → agent: «el prompt». Regla bajo el diagrama: «las flechas solo apuntan hacia abajo: ningún crate de la capa 2 depende de otro, salvo api → agent por el prompt».

```text
sypnia/
├── Cargo.toml                 el workspace, los lints compartidos, las dependencias fijadas
├── crates/
│   ├── sypnia-core/           (4) tipos y traits; sin red, sin disco, sin reloj propio
│   ├── sypnia-fingerprint/    (3) hash64, reglas de mensajes y marcos, listas por plataforma
│   ├── sypnia-store/          (3) ObjectStore sobre almacenes compatibles con S3 y sobre una carpeta; Keys
│   ├── sypnia-db/             (3) Database sobre Postgres; todas las sentencias SQL del motor
│   │   └── migrations/        numeradas, solo agregan, solo hacia adelante
│   ├── sypnia-ingest/         (2) las siete puertas, el búfer, subidas de grabaciones y capturas, conversión de OTLP
│   ├── sypnia-pipeline/       (2) vía rápida, problemas, agrupaciones, sesiones, source maps, Parquet, retención
│   ├── sypnia-agent/          (2) contexto, depuración, proveedores, la revisión, la plantilla del prompt
│   ├── sypnia-alerts/         (2) reglas de alertas, liberación, salidas, entregas de webhook, disponibilidad
│   ├── sypnia-api/            (2) la API HTTP, el servidor MCP, los archivos de la Consola
│   ├── sypnia/                (1) main, CLI, serve, lambda, Engine
│   └── sypnia-testkit/        horas grabadas y adaptadores en memoria, solo para pruebas
├── spec/                      openapi.yaml, events.schema.json, mcp.json, config.yaml, cli.yaml
├── vectors/                   vectores de prueba de huellas e histogramas, compartidos con los SDK
├── deploy/                    sypnia-aws.yaml, docker-compose.yaml, Dockerfile
└── console/                   la Consola: archivos simples, incluidos en el binario al compilar
```

| Crate                | Qué hace                                                                                                                                                                                                          | Se explica en                                                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `sypnia-core`        | `Event`, `ProjectId`, `Scope`, `Histogram`, la función de cuotas, los cuatro traits de puertos, los tipos de error. No hace entrada ni salida, así que compila en cualquier parte y sus pruebas no necesitan nada | [Resumen](https://docs.sypnia.com/es/architecture)                                                                                     |
| `sypnia-fingerprint` | `hash64` sobre unidades de código UTF-16, normalización de mensajes, lectura de marcos, las listas de marcos de ruido y las reglas de hash de compilación por plataforma                                          | [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping)                                                    |
| `sypnia-store`       | `ObjectStore` implementado sobre el crate `object_store`, y sobre una carpeta. `Keys`, el único lugar que conoce la disposición del bucket                                                                        | [Almacenamiento](https://docs.sypnia.com/es/architecture/storage)                                                                      |
| `sypnia-db`          | `Database` implementado con `sqlx`. Cada sentencia vive aquí como un archivo `.sql` revisado al compilar. El registro. Las migraciones                                                                            | [Almacenamiento](https://docs.sypnia.com/es/architecture/storage), [Agregación](https://docs.sypnia.com/es/architecture/aggregation)   |
| `sypnia-ingest`      | Los manejadores de `axum` para eventos, fragmentos de grabación, capturas, configuración y OTLP. `ProjectCache`. `Intake` y sus dos implementaciones: el búfer y la cola                                          | [Ingesta](https://docs.sypnia.com/es/architecture/ingest)                                                                              |
| `sypnia-pipeline`    | `fast_path`, `problems::transition`, las agrupaciones, el armado de sesiones, la traducción con source maps, la compactación, la retención                                                                        | [Flujo de datos](https://docs.sypnia.com/es/architecture/data-flow), [Agregación](https://docs.sypnia.com/es/architecture/aggregation) |
| `sypnia-agent`       | `build_context`, `redact`, `AiProvider` con `ChatCompletions` y `AnthropicMessages`, `check`, la plantilla del prompt, las sugerencias semanales                                                                  | [El proceso del agente](https://docs.sypnia.com/es/architecture/agent-pipeline)                                                        |
| `sypnia-alerts`      | Las nueve reglas de alertas, `release`, `AlertSink` con el registro y el webhook, los chequeos de disponibilidad                                                                                                  | [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping)                                                    |
| `sypnia-api`         | El lado de lectura: cada endpoint de `spec/openapi.yaml` que no es de ingesta, el servidor MCP, la Consola                                                                                                        | [Referencia de la API](https://docs.sypnia.com/es/api)                                                                                 |
| `sypnia`             | `main`, `Engine`, `serve`, `lambda`, los comandos de administración                                                                                                                                               | [Formas de despliegue](https://docs.sypnia.com/es/architecture/deployment-shapes)                                                      |
| `sypnia-testkit`     | `TestKit`: una carpeta como Bucket, un Postgres desechable, un reloj que tú pones, un proveedor que responde desde un archivo, y las horas grabadas                                                               | Esta página                                                                                                                            |

Dos reglas le dan forma al grafo (2):

- **Las partes no dependen unas de otras.** La ingesta no sabe que existe el pipeline; el pipeline no sabe que existe la API. Comparten tipos de `sypnia-core` y datos en el Bucket y en Postgres, que es exactamente como se despliegan por separado.
- **`sypnia-core` no hace entrada ni salida.** Una función ahí recibe valores y devuelve valores. Ahí viven las reglas que nunca deben desviarse: las entradas de la huella, el histograma, la decisión de cuotas, la transición de estado.

## Los traits y tipos principales

| Nombre                                     | Clase   | Crate                        | En una línea                                                                                                              |
| ------------------------------------------ | ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Event`                                    | enum    | core                         | Una línea de un segmento, etiquetada por `type`, con `extra` para campos desconocidos y `Unknown` para tipos desconocidos |
| `ProjectId`, `Scope`                       | structs | core                         | Un proyecto, y un proyecto con un entorno. Nada lee ni escribe sin un `Scope`                                             |
| `Fingerprint`                              | struct  | core                         | 16 caracteres hex                                                                                                         |
| `Histogram<N>`                             | struct  | core                         | Celdas fijas; `record`, `merge`, `percentile`                                                                             |
| `ObjectStore`                              | trait   | core, implementado en store  | `put`, `read_lines`, `get`, `list`, `delete_prefix`, `sign`                                                               |
| `Database`                                 | trait   | core, implementado en db     | Un método por sentencia, agrupados por tabla                                                                              |
| `AiProvider`                               | trait   | agent                        | `complete`: entra texto, sale texto, con conteos de tokens                                                                |
| `AlertSink`                                | trait   | core, implementado en alerts | `deliver` de una alerta liberada                                                                                          |
| `Intake`                                   | trait   | ingest                       | `append` de líneas validadas; regresa cuando están a salvo                                                                |
| `Clock`                                    | trait   | core                         | `now`. Real en producción, puesto a mano en las pruebas                                                                   |
| `Keys`                                     | struct  | store                        | Arma toda llave de objeto a partir de un `Scope`                                                                          |
| `Engine`                                   | struct  | sypnia                       | Los traits de arriba, conectados una vez; `pass` corre una ronda del worker                                               |
| `Failure`, `Transition`                    | enums   | pipeline                     | Lo que la vía rápida saca de una línea, y lo que le pasó a su problema                                                    |
| `HourFold`, `DeltaFold`                    | structs | pipeline                     | Los dos grupos de agrupaciones de la consolidación                                                                        |
| `Redacted<T>`                              | struct  | agent                        | Un valor que pasó la depuración. Lo único que acepta un proveedor                                                         |
| `EngineError` y un enum de error por crate | enums   | cada uno                     | Toda falla tiene una variante; la API convierte las variantes en los códigos de error del contrato                        |

## Las reglas del código

Seis reglas. Cada una la hace cumplir algo que rompe una compilación, no la memoria de quien revisa.

| Regla                                | Qué significa                                                                                                                                                                                | La hace cumplir                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Sin `unsafe`**                     | Ni un bloque, en ningún crate                                                                                                                                                                | `unsafe_code = "forbid"` en los lints del workspace                              |
| **Sin pánico por una entrada**       | Nada que envíe un SDK, un navegador, un bucket o un proveedor puede detener un proceso. Sin `unwrap`, `expect`, `panic!`, índices sin revisar ni aritmética sin revisar fuera de las pruebas | Lints de Clippy en `deny`; pruebas de fuzzing sobre `validate` y sobre la huella |
| **Toda escritura es idempotente**    | Sobrescribir con la misma llave, reemplazar, o sumar protegido por el registro. Una prueba corre cada paso dos veces y compara                                                               | Las pruebas de repetición de abajo                                               |
| **Nada sin un proyecto**             | Ningún método del almacén o de la base de datos recibe un texto suelto donde va un proyecto                                                                                                  | Los tipos: `Scope`, `Keys`, `ObjectKey`                                          |
| **La hora viene del `Clock`**        | Ningún `Utc::now()` fuera del único reloj real                                                                                                                                               | Un lint sobre el método prohibido; las pruebas ponen la hora                     |
| **El contrato es la especificación** | Un tipo de respuesta que no coincide con `spec/openapi.yaml`, un tipo de evento que no coincide con `events.schema.json` o un ajuste que no está en `config.yaml` hace fallar el CI          | Pruebas de contrato generadas desde `spec/`                                      |

Las dos primeras son unas pocas líneas al inicio del workspace. Fíjate en que los lints están en `deny`, no en `warn`: una compilación con un `unwrap` en código del motor no produce un binario.

`Cargo.toml`

```toml
[workspace]
members = ["crates/*"]
resolver = "2"

[workspace.package]
edition = "2021"
license = "AGPL-3.0-only"
rust-version = "1.82"

[workspace.lints.rust]
unsafe_code = "forbid"
missing_debug_implementations = "warn"

[workspace.lints.clippy]
unwrap_used = "deny"            # las pruebas se excluyen con #[cfg(test)] allow
expect_used = "deny"
panic = "deny"
indexing_slicing = "deny"       # usa .get(), o demuestra el límite en el tipo
arithmetic_side_effects = "deny" # los contadores usan saturating_add
disallowed_methods = "deny"     # clippy.toml lista chrono::Utc::now y std::time::SystemTime::now

[workspace.dependencies]
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "signal"] }
axum = "0.7"
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["raw_value"] }
sqlx = { version = "0.8", features = ["runtime-tokio", "tls-rustls", "postgres", "chrono", "json"] }
object_store = { version = "0.11", features = ["aws"] }
```

Cómo se ve en la práctica «sin pánico por una entrada»: un error es un valor con una variante, y el borde del motor lo convierte en la respuesta que promete el contrato. Fíjate en que la conversión es un solo `match` exhaustivo: agregar una variante sin decidir su código de estado no compila.

`crates/sypnia-ingest/src/error.rs`

```rust
#[derive(Debug, thiserror::Error)]
pub enum IngestError {
    #[error("the ingest key is missing, unknown or revoked")]
    Unauthorized,
    #[error("an API token was sent to an ingest endpoint")]
    WrongCredential,
    #[error("origin not allowed for this key")]
    OriginNotAllowed,
    #[error("too many requests from this address")]
    RateLimited { retry_after: Duration },
    #[error("the body is not valid JSON or gzip")]
    InvalidBody,
    #[error("more than 200 events in one batch")]
    TooManyEvents,
    #[error("the body is larger than the limit after decompression")]
    PayloadTooLarge,
    #[error("storage is not reachable")]
    Unavailable,
}

impl IntoResponse for IngestError {
    fn into_response(self) -> Response {
        let (status, code, retry_after) = match &self {
            Self::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized", None),
            Self::WrongCredential => (StatusCode::FORBIDDEN, "wrong_credential", None),
            Self::OriginNotAllowed => (StatusCode::FORBIDDEN, "origin_not_allowed", None),
            Self::RateLimited { retry_after } => (StatusCode::TOO_MANY_REQUESTS, "rate_limited", Some(*retry_after)),
            Self::InvalidBody => (StatusCode::BAD_REQUEST, "invalid_body", None),
            Self::TooManyEvents => (StatusCode::BAD_REQUEST, "too_many_events", None),
            Self::PayloadTooLarge => (StatusCode::PAYLOAD_TOO_LARGE, "payload_too_large", None),
            Self::Unavailable => (StatusCode::SERVICE_UNAVAILABLE, "unavailable", Some(Duration::from_secs(2))),
        };
        api_error(status, code, self.to_string(), retry_after) // { "error": { code, message, doc_url, request_id } }
    }
}
```

## Pruebas que repiten horas grabadas

Una prueba unitaria puede demostrar una función. No puede demostrar que una hora de tráfico real, llegando en el orden y en los pedazos en que de verdad llegó, termina en las filas correctas. Por eso las pruebas principales del motor son grabaciones.

Una **hora grabada** es una carpeta: cada lote que llegó a la ingesta en una hora, cada uno con la hora en que llegó, y al lado las filas y los objetos que esa hora debe producir. La primera es la hora sintética del sistema del que sale este motor: tres sesiones con métricas vitales, clics, errores, solicitudes y sus registros del servidor. Sus filas esperadas son las que produjo el pipeline original, y eso hace de la prueba una demostración de paridad, no solo de consistencia.

**Figura (diagrama aún sin dibujar)**: Una prueba de repetición. Una hora pasa por todo el motor, y luego se le hacen cuatro cosas que ocurren en producción. Las filas no deben cambiar.

Mostrará: El mismo diagrama de flujo de una prueba de repetición que la figura 2 de la página en inglés (architecture/codebase), con los mismos nodos, el ciclo, llamadas (1) a (4) y el mismo elemento encendido (la comparación). Rótulos traducidos: 1 «Hora grabada» («hours/shop-2026-03-12T09/ · 41 lotes con su hora de llegada»); flecha «se repiten en orden, con el reloj puesto en cada hora de llegada»; 2 «TestKit» con el motor adentro: «Ingesta» → «Bucket (una carpeta)» → «Vía rápida» y «Consolidación» → «Postgres (desechable)»; 3 «Instantánea» («cada tabla, cada llave de objeto, como texto»); flecha «comparar»; 4 «Instantánea esperada (en el repositorio)». Etiquetas del ciclo: «1 correr la pasada otra vez», «2 enviar cada lote por segunda vez», «3 detener la consolidación antes de confirmar y correrla de nuevo», «4 correr dos workers a la vez». Línea bajo el ciclo: «después de cada una, la instantánea debe ser idéntica».

Fíjate en que la prueba de abajo nunca afirma un número suelto. Afirma que todo el resultado es igual al grabado, y luego que nada de lo que puede hacer un reintento lo cambia.

`crates/sypnia-pipeline/tests/replay_shop_hour.rs`

```rust
#[tokio::test]
async fn the_shop_hour_survives_everything_a_retry_can_do() {
    // Una carpeta como Bucket, un Postgres desechable con las migraciones aplicadas, un reloj que ponemos nosotros.
    let kit = TestKit::start().await;
    let hour = RecordedHour::load("hours/shop-2026-03-12T09");

    // Cada lote pasa por el manejador real de la ingesta a la hora en que de verdad llegó.
    kit.replay(&hour).await;
    kit.run_until_idle().await; // pasadas del worker, hasta que el registro no tenga nada nuevo
    let first = kit.snapshot().await; // cada tabla y cada llave de objeto, como texto ordenado
    insta::assert_snapshot!("shop_hour", first);

    // 1. Correr otra vez no cambia nada.
    kit.engine.pass().await.unwrap();
    assert_eq!(first, kit.snapshot().await, "a second pass changed the result");

    // 2. Cada lote llega por segunda vez: se guarda, nunca se cuenta.
    kit.replay(&hour).await;
    kit.run_until_idle().await;
    assert_eq!(first.rows(), kit.snapshot().await.rows(), "duplicated batches were counted");

    // 3. La consolidación muere justo antes de confirmar, y luego corre de nuevo.
    let fresh = TestKit::start().await;
    fresh.replay(&hour).await;
    fresh.fail_once(FailPoint::BeforeRollupCommit);
    assert!(fresh.engine.pass().await.is_err());
    fresh.run_until_idle().await;
    assert_eq!(first, fresh.snapshot().await, "a failed run left something behind");

    // 4. Dos workers a la vez: gana una reserva, el resultado es el mismo.
    let racing = TestKit::start().await;
    racing.replay(&hour).await;
    let (a, b) = tokio::join!(racing.engine.pass(), racing.engine.pass());
    assert!(a.is_ok() && b.is_ok());
    racing.run_until_idle().await;
    assert_eq!(first, racing.snapshot().await, "two workers disagreed");
}
```

Las demás clases de prueba, y qué protege cada una:

| Pruebas                     | Protegen                                                                                                                                                                                                                                                         |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vectors/fingerprints.json` | Las mismas entradas y huellas esperadas las corren este crate y los SDK. Una diferencia de un bit rompe las dos compilaciones. El ejemplo calculado a mano en [Agrupación de problemas](https://docs.sypnia.com/es/architecture/problem-grouping) es el vector 1 |
| `vectors/histograms.json`   | Celdas y percentiles para valores conocidos, compartidos con todo lo que lea los arreglos                                                                                                                                                                        |
| Pruebas de contrato         | Cada ejemplo de `spec/openapi.yaml` y `spec/events.schema.json` se envía a los manejadores reales; cada respuesta se revisa contra su esquema                                                                                                                    |
| Suites portadas             | Las pruebas de ingesta, agregación, source maps y upserts del sistema del que sale esto, traducidas: sus listas de excepciones para clics muertos falsos y errores ajenos son conocimiento del producto                                                          |
| Fuzzing                     | `validate`, el lector de pilas y el conversor de OTLP deben regresar, nunca entrar en pánico, con cualquier secuencia de bytes                                                                                                                                   |
| Pruebas de presupuesto      | Una hora grabada diez veces más grande debe consolidarse dentro de 256 MB y dentro de su presupuesto de tiempo                                                                                                                                                   |

## Córrelo en tu máquina

**Al final tendrás:** el motor corriendo localmente en un proceso, un proyecto, y el problema de ejemplo en la lista.

Necesitas Rust (la versión de `rust-toolchain.toml`) y Docker, para Postgres y un almacenamiento compatible con S3.

### 1. Arranca Postgres y un bucket

```bash
docker compose -f deploy/docker-compose.dev.yaml up -d
```

**Deberías ver:**Dos contenedores corriendo: Postgres en el puerto 5432 y MinIO en el puerto 9000, con un bucket llamado `sypnia-dev`.

### 2. Apunta el motor a ellos

```bash
cp .env.example .env    # URL base http://localhost:8080, la base de datos y el bucket locales, un token raíz
set -a; source .env; set +a
```

**Deberías ver:**`echo $SYPNIA_BASE_URL` imprime `http://localhost:8080`.

### 3. Crea las tablas

```bash
cargo run -- migrate
```

**Deberías ver:**La lista de migraciones aplicadas, que termina con `database is up to date`.

### 4. Corre el motor

```bash
cargo run -- serve
```

**Deberías ver:**

```text
sypnia 1.0.0  role=all  listen=0.0.0.0:8080
database  ok  postgres 16.4, schema 12
storage   ok  s3://sypnia-dev (us-east-1)
ai        off (SYPNIA_AI_PROVIDER=none)
ready     http://localhost:8080
```

### 5. Crea un proyecto y envía el ejemplo

En una segunda terminal, con el mismo `.env` cargado:

```bash
cargo run -- project create --name Shop
curl -X POST "$SYPNIA_BASE_URL/v1/ingest/events" \
  -H "Authorization: Bearer <la llave spk_ que se imprimió>" \
  -H "Content-Type: application/json" \
  --data @crates/sypnia-testkit/hours/shop-2026-03-12T09/batch-0007.json
```

**Deberías ver:**`{"accepted":2,"dropped":0}`. En la primera terminal, en pocos segundos, una línea del worker que dice `1 problem (1 new)`.

### 6. Mira el problema

```bash
cargo run -- problems --project shop
```

**Deberías ver:**Un problema abierto, `createPayment answered 400 in POST /api/checkout`, con 1 persona. La Consola muestra lo mismo en `http://localhost:8080/console`.

Para correr las pruebas: `cargo test --workspace`. Las pruebas de repetición arrancan su propio Postgres con Docker y no necesitan nada más. `cargo run -- doctor` revisa una configuración pieza por pieza cuando algo no arranca.

## Cómo fluye una contribución

El motor se construye con la documentación primero, y una contribución sigue el mismo orden.

**Figura (diagrama aún sin dibujar)**: Cómo entra un cambio. La página cambia antes que el código, y siete revisiones automáticas separan un pull request de una revisión.

Mostrará: El mismo diagrama de flujo de seis pasos que la figura 3 de la página en inglés (architecture/codebase), con el carril inferior de siete revisiones, las mismas flechas y el mismo elemento encendido (el paso 2). Rótulos traducidos: 1 «Issue: qué debe cambiar, y por qué»; 2 «Primero cambia la documentación» («la página, y el archivo de spec/ si se mueve un contrato»); 3 «El código, con sus pruebas»; 4 «Pull request»; 5 «Revisión de un mantenedor»; 6 «Mezclar, y luego una versión». Carril inferior, llave «CI: todas deben pasar»: «formato», «lints: sin unsafe, sin unwrap», «pruebas unitarias», «pruebas de repetición», «vectores compartidos», «pruebas de contrato contra spec/», «las migraciones solo agregan». Flecha de 5 a 3: «cambios pedidos». Nota en 2: «un cambio de comportamiento sin cambio en la documentación no se revisa». Nota en 6: «el registro de cambios lo nombra».

1. **Abre un issue** que diga qué debe cambiar y por qué. Para un error, el mejor reporte es un lote grabado que lo muestre.
2. **Cambia primero la documentación.** Si el cambio altera el comportamiento, la página que lo describe cambia en el mismo pull request, y también el archivo de `spec/` cuando se mueve un endpoint, un evento, un ajuste o un comando. Quien revisa lee la página antes que el código.
3. **Escribe el código y sus pruebas.** Un camino nuevo por el pipeline llega con una hora grabada, o con un agregado a una. Una sentencia SQL nueva llega con la prueba que la corre dos veces.
4. **Abre el pull request.** El CI corre las siete revisiones de la figura. La revisión de migraciones rechaza una migración que borre o renombre: las versiones vieja y nueva del motor deben poder correr contra las mismas tablas durante una actualización.
5. **Un mantenedor revisa.** Busca las reglas de esta página antes que cualquier otra cosa: si toda escritura nueva es idempotente, si algo recibe un proyecto como texto suelto, si alguna entrada puede llegar a un pánico.
6. **Mezcla y versión.** Las versiones siguen la regla de la API: dentro de la versión 1, solo se agrega.

Algunos cambios no se aceptan como pull request, porque son decisiones y no código: un servicio obligatorio nuevo junto al Bucket y Postgres, un cambio en la huella que partiría problemas existentes, un cambio en los límites de los histogramas, una integración que envíe alertas a un producto de chat. Para esos, abre un issue y conversemos.

El motor y la Consola están bajo AGPL-3.0; los SDK y `@sypnia/mcp`, bajo MIT. Qué significa eso para quien lo aloja, lo modifica o contribuye, y los términos con los que se acepta una contribución, están en [Contribuir](https://docs.sypnia.com/es/licensing/contributing).

|                           | Motor de Sypnia (código abierto, en tu propia infraestructura)                                         | Sypnia Cloud (servicio pago, con un plan gratis)                                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Este repositorio          | Todo lo de esta página: los once crates, las especificaciones, los archivos de despliegue, la Consola. | El mismo código, desplegado por nosotros desde las mismas versiones.                                                                                                                |
| Fuera de este repositorio | Al motor no se le retiene nada.                                                                        | Las cuentas y organizaciones, la facturación, la app, el envío de correo, la GitHub App y el modelo administrado viven en un repositorio privado. Usan el motor por su API pública. |

## Por dónde empezar a leer

| Si quieres entender                  | Abre                                                                                      |
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
| Qué es un evento                     | `crates/sypnia-core/src/event.rs`                                                         |
| Qué le pasa a una solicitud          | `crates/sypnia-ingest/src/events.rs`, luego `buffer.rs`                                   |
| Cómo nace un problema                | `crates/sypnia-pipeline/src/fast_path.rs`, luego `problems/transition.rs`                 |
| Cómo se cuenta un número             | `crates/sypnia-pipeline/src/fold/pages.rs`, luego `crates/sypnia-db/src/rollup_commit.rs` |
| Por qué dos fallas son la misma      | `crates/sypnia-fingerprint/src/lib.rs` y `vectors/fingerprints.json`                      |
| Qué se le envía al modelo            | `crates/sypnia-agent/src/context.rs`, luego `check.rs`                                    |
| En qué se diferencian las dos formas | `crates/sypnia/src/serve.rs` y `lambda.rs`                                                |
| Si una regla de verdad se cumple     | `crates/sypnia-pipeline/tests/replay_shop_hour.rs`                                        |

## Sigue
