De Beta a v1: El contrato que Invariant debe ganarse

Invariant ya tiene un contrato Beta real: workflows y agentes tipados, estado de ejecución durable, eventos append-only, intención transaccional de comandos, Sessions, proyecciones, concurrencia optimista, leases y adaptadores para SQLite y PostgreSQL.

Es un avance importante. No equivale a estar listo para v1.

Una versión estable debe significar más que eliminar -beta del número de un paquete. Debe decirle a un equipo de ingeniería qué seguirá siendo compatible, qué ocurre cuando un proceso falla en el peor momento posible, cómo evolucionan los datos persistidos y cuáles responsabilidades operativas pertenecen a Invariant o a la aplicación host.

Qué garantiza hoy la Beta

El contrato 0.1.0-beta.1 establece varias bases que queremos conservar:

• La topología de workflows y las Runtime Actions limitan lo que un modelo puede proponer.
• Los stores configurados confirman atómicamente estado de ejecución, eventos durables e intención de comandos mediante control de concurrencia optimista.
• Las ejecuciones nuevas reciben identidades UUID generadas por el host.
• La identidad durable de eventos se deriva de ${runId}:${sequence}.
• La revisión autoritativa avanza una vez por cada evento durable, incluso cuando una transición emite múltiples eventos.
• SQLite y PostgreSQL implementan el mismo contrato de almacenamiento para estado, eventos, comandos, Sessions, leases y descubrimiento de ejecuciones reanudables.
• Los historiales Beta persistidos siguen siendo legibles y reproducibles.
• Las propuestas inválidas o caducadas se rechazan antes de confirmar progreso autoritativo.

Son garantías del runtime, no convenciones escritas en prompts. Están respaldadas por pruebas del reducer, SDK, stores, PostgreSQL real, snippets, builds y consumidores externos.

Pero la frontera importa tanto como la garantía.

La limitación más importante de la Beta

El host actual despacha los comandos confirmados en proceso. Los stores durables exponen leases e IDs de ejecuciones reanudables, pero la API pública todavía no contiene todas las operaciones necesarias para un loop portable de recuperación:

• no existe un contrato atómico de claim y acknowledgement para comandos pendientes;
• no existe una API soportada para adjuntar una ejecución desde otro proceso;
• no se incluye un scanner o worker de recuperación en segundo plano;
• no se incluye un scheduler automático de timers.

Los hechos persistidos permiten reconstruir la verdad confirmada. Eso no significa que un proceso nuevo pueda convertirse automáticamente en el dueño vivo de una ejecución interrumpida.

La diferencia está documentada en la Matriz del Contrato de Recuperación. Hasta que existan las operaciones faltantes, la continuación cross-process queda a cargo de la aplicación.

Los efectos externos también mantienen semántica at-least-once cuando se vuelven a despachar. Las claves estables de idempotencia reducen el riesgo de duplicados solo cuando el proveedor externo las respeta. Invariant no promete ejecución exactly-once entre una base de datos y un sistema externo independiente.

Esta es la brecha técnica más grande entre Beta y v1.

Qué debe ser verdad antes de v1

1. Un contrato completo de recuperación cross-process

Las APIs públicas de storage y host deben soportar el ciclo completo de trabajo interrumpido:

descubrir ejecución reanudable
        ↓
adquirir ownership con fencing
        ↓
adjuntar y reconstruir la ejecución
        ↓
reclamar el comando pendiente atómicamente
        ↓
despachar con la misma identidad de idempotencia
        ↓
confirmar, reintentar o terminar explícitamente

Esto incluye renovación y expiración de leases, programación de reintentos, backoff limitado, tratamiento de comandos defectuosos y continuación de .wait() desde un proceso nuevo. Las pruebas de inyección de fallos deben cubrir cada frontera antes y después del efecto externo.

2. Semántica estable de efectos

v1 debe documentar una sola respuesta precisa para cada pregunta:

• ¿Qué identidad recibe el proveedor externo?
• ¿Qué se vuelve durable antes del despacho?
• ¿Qué ocurre después de un timeout ambiguo?
• ¿Cómo conserva un reintento la identidad del comando?
• ¿Cuándo se vuelve terminal un comando?
• ¿Qué puede intentar una compensación y qué jamás puede garantizar?

La respuesta seguirá basada en entrega at-least-once e idempotencia del proveedor, no en marketing exactly-once.

3. Evolución de schemas y seguridad de datos

La infraestructura persistente necesita una historia de upgrades. Antes de v1, los schemas de SQLite y PostgreSQL requieren versiones explícitas, migraciones hacia adelante, guías de backup y restore, procedimientos de rollback y pruebas de compatibilidad contra historiales anteriores.

Un runtime no es durable si una actualización vuelve ilegibles las ejecuciones de ayer.

4. Seguridad y fronteras entre tenants

El reingreso en .wait(), las Sessions, los webhooks, endpoints MCP, tokens de audio en vivo, traces y storage cruzan fronteras de confianza. v1 requiere un threat model publicado y una división explícita de responsabilidades para autenticación, autorización, aislamiento de tenants, secretos, PII, retención y redacción.

5. Observabilidad y runbooks de producción

Un operador debe poder responder:

• ¿Qué ocurrió con esta ejecución?
• ¿Qué revisión y secuencia de eventos son autoritativas?
• ¿Quién posee el lease?
• ¿Qué comando está pendiente o reintentándose?
• ¿Por qué se detuvo la ejecución?

Schemas estables de traces, señales de salud, ejemplos de sinks y runbooks para leases caducados, caídas de proveedores, comandos defectuosos y divergencias de replay forman parte del contrato v1; no son detalles opcionales.

6. Evidencia de compatibilidad y release

La API estable debe probarse desde afuera, usando los mismos artefactos que instalan los usuarios. El gate final comienza desde un único commit limpio e inmutable y exige:

SHA limpio
  → build, typecheck y tests
  → conformidad real de SQLite/PostgreSQL
  → checks de docs y snippets protegidos
  → empaquetar los nueve paquetes
  → verificar hashes y provenance
  → smoke tests de consumidor externo
  → preflight de npm
  → período de prueba del release candidate
  → publicación y verificación post-deploy

Ningún paquete debe reconstruirse entre la verificación y la publicación. La documentación, el landing, los paquetes npm, el changelog y la matriz de soporte deben mostrar la misma versión y las mismas garantías.

Qué no significará v1

v1 no significará que ya construimos todos los adaptadores, schedulers, interfaces o modelos de despliegue posibles.

Tampoco significará que los efectos externos se vuelven mágicamente exactly-once. No convertirá una compensación declarada en una reversión garantizada de la realidad externa. No convertirá un proyecto bajo Elastic License 2.0 en open source aprobado por la OSI; Invariant seguirá siendo source-available, como explico en Por qué elegí ELv2.

Significará que la superficie soportada es deliberada, compatible, operable y honesta.

Las capacidades fuera de esa superficie podrán seguir evolucionando después de v1 sin debilitar el contrato central.

Un checklist público basado en evidencia

El checklist completo vive en el repositorio como Invariant Beta → v1 Release Checklist.

Una tarea solo se considera completa cuando enlaza evidencia reproducible desde un commit limpio. La documentación o intención arquitectónica por sí solas no cuentan.

No asignamos una fecha artificial a esta transición. El objetivo no es llegar a v1 lo más rápido posible. El objetivo es que 1.0.0 signifique algo en lo que los equipos de ingeniería puedan confiar.

Si estás evaluando Invariant hoy, comienza con el Quick Start, lee las Garantías de Durabilidad y considera la Matriz del Contrato de Recuperación como la frontera autoritativa del release actual.