El substrato soberano
Actualizado al 24-oct-2026 (main
f41235c7).
El substrato es el plano de control soberano del sistema. La idea rectora: lo que define quién puede hacer qué, con qué datos y bajo qué reglas, es nuestro; la infraestructura pesada vive detrás de puertos con adaptadores reemplazables.
Diagrama del diseño original (julio de 2026)
Sección titulada «Diagrama del diseño original (julio de 2026)»Este diagrama describe el diseño de julio de 2026 y no se regeneró. Dos de sus afirmaciones ya no son ciertas: dice «48 ops» (el catálogo tiene 75 al 24-oct-2026) y presenta a Inngest como quien corre los pasos con reintentos (hoy los pasos los mueve el motor propio descrito más abajo). Las demás cajas, Nova, approvals, FORGE y Postgres como fuente de verdad, siguen vigentes. Lo vigente es el texto de esta página.
Nova, la puerta de discovery
Sección titulada «Nova, la puerta de discovery»Nova es el agente que recibe la necesidad en lenguaje natural y la convierte en un squad. No es un formulario ni un selector: interpreta, propone un equipo de dos o tres agentes (la propuesta de Nova Discovery usa el modelo anthropic/claude-opus-5) y ajusta la propuesta hasta que el usuario confirma. En el Acuerdo de Operación, Nova coordina y explica cómo trabaja el equipo.
Rutas: /api/discovery/chat (discovery) y /api/discovery/charter (Acuerdo de Operación).
Cuando ya hay un squad, cada pedido pasa por el compose de Nova (/api/workspaces/:id/compose), que decide entre siete desenlaces tipados: conversar, proponer una aprobación, reusar un workflow curado, reusar un SuperSkill propio, armar un plan a medida, declarar que no se puede y fallo de armado. Un plan a medida queda como borrador propuesto y nunca se ejecuta dentro del compose: la persona lo lanza después. En producción el compose es asíncrono (COMPOSE_ASYNC=on): la ruta responde 202 con un task_id y una función de Inngest ejecuta la composición.
API Hono sobre Bun
Sección titulada «API Hono sobre Bun»apps/api es la superficie HTTP del substrato. Monta 53 módulos de rutas: discovery, workspaces, compose, intents, FORGE, approvals, voz, SLO, administración y más. Sobre ella corre la orquestación: traducir intents y composiciones en operaciones del catálogo y arrancar su corrida.
La autenticación tiene capas:
- Un Bearer (
SUBSTRATE_API_TOKEN) cubre/api/me, workspaces, approvals, intents, SLO, FORGE, administración, discovery y tenants. Sin token configurado la API responde 503. - Un token de delegación firmado ata cada pedido a un usuario y un workspace. En producción está en modo de rechazo (
DELEGATION_ENFORCE=on) y el compose asíncrono lo exige. - Las rutas de reset usan otro Bearer; voz y el log de cliente tienen autenticación propia; las rutas
/api/demo/*y el callback de OAuth de YouTube son públicas. - El rate limit es en memoria, por proceso, y tiene un tope distinto por ruta (por ejemplo, compose 4 por minuto y chat 10 por minuto).
Motor de ejecución v2 e Inngest
Sección titulada «Motor de ejecución v2 e Inngest»Las operaciones no corren en el request HTTP. El flujo es:
POST /api/intentsdeclara el intent y emiteintent.declared.- Una función de Inngest compila la plantilla a un grafo (
graphsygraph_nodes), con uncontent_hashque sirve de clave de idempotencia, y arranca la corrida v2. - La corrida escribe en
run_events, un log donde cada evento tiene una clave única derivada de su causa (sin duplicados) y un número de secuencia sin huecos. Un reducer puro decide las transiciones; los efectos se cumplen en la misma transacción que el evento. - Los nodos listos se encolan en
work_items, una cola de comandos con lease. Un cron de Inngest despierta al worker cada minuto; cada tanda toma hasta cinco items y los ejecuta en paralelo, después de re-autorizar cada nodo contra el roster del workspace. - Otro cron devuelve a la cola los leases vencidos; tras varias recuperaciones un item queda como muerto.
- Un nodo fallido se reintenta hasta tres intentos en total, salvo decisiones humanas, evaluaciones bloqueantes y errores determinísticos.
Inngest conserva el papel de entrada durable, cron y tick del worker: 18 funciones registradas al 24-oct-2026. Cambiar el id, los triggers o la concurrencia de una función exige un re-sync manual con Inngest; ni el CI ni el auto-deploy lo hacen. El executor anterior (v1, basado en step.run y waitForEvent) está marcado como obsoleto, fuera del registro, y una prueba falla si alguien lo vuelve a conectar.
La idempotencia y la reversibilidad son requisitos, no adornos: es la zona de mayor cuidado del sistema.
Postgres, fuente de verdad
Sección titulada «Postgres, fuente de verdad»Todo el estado con autoridad vive en Postgres 16 con las extensiones pgcrypto, vector y vectorscale. Al 24-oct-2026 la base de producción tiene 85 tablas; 70 con RLS activa por workspace y una (operator_failed_llm_outputs) con RLS forzada. La API se conecta con el rol substrate_app (sin bypass de RLS) y fija el workspace por transacción; hay roles aparte para recuperación, mantenimiento, administración y resets.
Las migraciones son 126, de 0001 a 0126, y se aplican a mano antes de fusionar el cambio que las usa: no hay herramienta de migraciones ni tabla de versiones. El manejo de datos sensibles también es zona de alto riesgo: la anonimización con Presidio sube el nivel de custodia a confidencial y nunca lo baja.
Respaldos: pg_dump diario a las 03:00 con copia a Cloudflare R2, pgBackRest incremental diario a las 04:00 y un simulacro de restauración semanal (el último exitoso fue el 18-oct-2026).
FORGE, el plano generativo
Sección titulada «FORGE, el plano generativo»FORGE genera y ejecuta código del modelo en un sandbox por proceso (bwrap). La generación usa la clase de modelo compose por el gateway, no un CLI local. No es libre:
- Una operación con
tool_bindingsolo puede forjarse si su capability está en la listaFORGEABLE_CAPABILITIES, una decisión humana explícita. Hoy son tres:demo.gateway_probe,slack.postygithub.gist_create. - Un chequeo estático bloquea patrones peligrosos (red, sistema de archivos, procesos,
eval, acceso a variables de entorno). - Tope de dos forjas por workspace y hora, hasta cuatro intentos de implementación y un build gate humano de 72 horas.
FORGE está activo en producción (FORGE_ENABLED=true); sin ese flag el compose no propone forjar. Existe además un brazo alternativo (Eve) apagado y sin cambios desde junio de 2026.
Approvals, los puntos de decisión humana
Sección titulada «Approvals, los puntos de decisión humana»Los approvals son donde el substrato se detiene y espera al humano. El Acuerdo de Operación los hace explícitos: cada agente tiene un alcance, y hay puntos donde la decisión es de la persona antes de que el trabajo avance. Rutas: /api/approvals y /api/approvals/*.
En el motor v2 un gate es un nodo en espera más un registro en artifact_approval_flows. Todas las plantillas con gate vencen a las 72 horas y su fallback es fail: la auto-aprobación está prohibida. Un barrido por minuto aplica el fallback a los gates vencidos. El brief usa un gate de dos fases: primero la persona revisa (y puede editar) el brief, después elige el ángulo.
Modelos y observabilidad
Sección titulada «Modelos y observabilidad»- Modelos: en producción toda llamada a un modelo pasa por el Vercel AI Gateway; ningún nodo de producción invoca un CLI de modelo, y el CI lo verifica. Cada llamada se registra en la tabla
llm_calls. - Observabilidad: OpenTelemetry hacia Honeycomb (dataset
agentsquadtraces) y Phoenix para trazas de LLM. Langfuse se retiró el 22-ago-2026: sus contenedores se eliminaron y hoy la observabilidad de LLM es Phoenix.