El arco tiene dos etapas: primero el anillo de verificación (el asiento con mejor vista del sistema entero), después una pieza del catálogo con tu nombre. Todo lo de esta guía es verificable con un comando: acá nada "está listo" porque alguien lo diga, está listo porque algo lo recorrió y lo probó.
Cada checkpoint tiene su comando y su resultado esperado. Si un número no te da, NO sigas: avisale a tu mentor con el output completo: un entorno torcido te va a hacer perder días persiguiendo fantasmas.
No leas "todo el repo": leé estas 10 piezas en orden y anotá UNA pregunta por archivo para tu mentor. El orden importa: va del borde al corazón.
Cómo se especifica acá: cada task con archivos exactos y un bloque Done when verificable (116 de los 126 planes de esa carpeta lo traen, al 24-oct-2026). Vas a escribir los tuyos igual.
El arranque del servidor completo (705 líneas): qué rutas van detrás de qué guardia (bearer, token de delegación, límites de ritmo). Notá el idleTimeout: 255 y preguntate por qué existe: es una cicatriz real. El default de Bun (10 s) mataba el streaming del chat cuando el modelo razonaba en silencio, y 255 es lo máximo que Bun acepta.
Una ventana deslizante con reloj inyectable (55 líneas). Es la clase magistral de "cómo hacer testeable algo que depende del tiempo". Después buscá en index.ts qué límites usa cada ruta.
Una plantilla es un grafo tipado de pasos: qué operación hace cada uno, qué reintentos tiene, dónde está la compuerta humana. Casi ningún paso trae actor fijo (solo el evaluador system:evaluator y el dueño humano human:owner): el resto se ata al roster del workspace al lanzar. Acá entendés qué ES el trabajo en este sistema.
El catálogo en ejecución: 71 handlers registrados (el catálogo tiene 75 pares id@versión, al 24-oct-2026). Los que faltan no son un olvido: human_gate.approve y human_task los resuelve el propio motor (la corrida queda esperando a una persona), y slack.post y github.gist_create solo se pueden despachar si FORGE forjó una capacidad con ese id. Cuando entiendas por qué, entendiste la arquitectura.
assertHumanGatePresent: la gobernanza escrita como código. Ningún plan que pase por launchCompiledPlan (los que compone Nova y los SuperSkills propios) puede lanzarse sin un gate humano terminal, y todo gate tiene que fallar al vencer: la auto-aprobación no existe.
El lugar donde el modelo "diseña" planes, y por eso de los más vigilados: solo operaciones del catálogo, grafo sin ciclos (isAcyclic), tope de 16 pasos y de 4 pasos con modelo, y el costo estimado (cost_estimate) lo calcula el servidor. Mirá también los 7 desenlaces posibles. La filosofía de la casa: validá al modelo, no le creas.
El guardián de CADA request: cookie, refresh de sesión, gate de acceso que falla cerrado (error al leer = no autorizado), workspace del usuario y gate de onboarding. Mirá también el triple candado del bypass de tests (dev, CI=true y NODE_ENV distinto de production).
La cola de escritura: por qué dos escrituras del estado del usuario no se pisan, la generación que corta a una pestaña que quedó del otro lado de un reset, y el revert si la escritura falla. Todo estado del usuario pasa por acá, nunca por un fetch directo.
El modelo de datos fundacional: intents, artifacts y claims, con la regla de que todo claim y artifact tiene un camino de linaje hasta su origen. Leé los comentarios SQL, que explican cada porqué (ojo: el de las 3072 dimensiones quedó viejo, los embeddings de hoy son de 384). Después leé apps/api/db/substrate/migrations/0044_orquestacion_v2_fase0.sql, donde nacen las corridas (runs, run_events, work_items) que reemplazaron a plans, traces y step_executions.
Semanas 1-3. Para verificar un paso tenés que entender todas las capas que atraviesa, por eso se empieza acá.
Elegí con tu mentor un flujo chico sin cubrir. El patrón de la casa: la web se prueba contra un mock del motor en el puerto 4998: sin LLM, sin producción, determinista.
tests/e2e/16b-nova-compose.spec.ts y tests/e2e/helpers/substrate-mock.ts: ahí está el patrón completo (handlers por endpoint, beforeEach que resetea estado).waitForLoadState('networkidle') antes de cada click: sin ese gate, los listeners pueden no estar montados.Semanas 4+. La Operation es LA unidad de aprendizaje: contrato tipado, costo, reintentos, evaluación. Chica, real y segura.
Con tu mentor definan una operation SIN LLM (ej.: una transformación de texto, un agregado sobre claims existentes). Sin modelo en el medio, el feedback es instantáneo y aprendés el contrato puro.
packages/substrate-spec/src/operations/) y agregala a la lista REGISTERED de operations/catalog.ts: id versionado (tuop.algo@1.0.0), inputs y output tipados, side_effects declarado. Mirá cómo lo hace audience.load: no usa modelo y solo lee un archivo.apps/api/src/inngest/operations/).apps/api/src/inngest/operations/ y registralo en operations/index.ts con registerOperation.costoSinLlamada() (apps/api/src/substrate/costo-operacion.ts). Un costo sin el campo de caja se lee como desconocido, y a partir de ahí la corrida deja de autorizar gasto adicional.Ninguna es teórica: todas salieron de un incidente real. Conocer la cicatriz es lo que evita repetirla.
CI=true para todo E2E local.Sin eso el bypass de auth no se activa y vas a "encontrar" regresiones que no existen.generateLLMText.La suite del motor corre sin gateway y con LLM_CALLS_PERSIST=off (apps/api/vitest.config.ts): un test que llame al modelo de verdad cuesta plata y no tiene que escribir en llm_calls. Y un mock que reemplaza exports de más tapa comportamiento real. (El origen fue un incidente de junio con el runner nativo de Bun, donde el mock de módulos es global; no se reverificó hoy.)state_generation): una pestaña que quedó del otro lado de un reset recibe un 409 y no puede revivir lo borrado. La cola de userState.ts ordena las escrituras y revierte si una falla; un fetch directo se salta las dos cosas.apps/web/src/lib/office/manifiesto-line.test.ts).scripts/reset-user.sh), pero lo que lanzás en producción consume modelos reales y deja datos. Tu mentor limpia tu workspace de prueba al terminar el lab, y vos nunca aprobás ni borrás nada que no hayas creado vos.deploy del CI y la API por un cron cada 3 minutos que despliega solo con el CI verde. Durante esa ventana el motor viejo habla con la web nueva, o al revés (un comentario de apps/web/src/lib/squads/store.ts lo cuenta con un caso real). Diseñá cada cambio de contrato para que sobreviva a las dos mitades: aditivo, con valores por defecto, y que degrade sin romper.| Término | Qué es |
|---|---|
| Intent | El pedido por escrito: qué quiere lograr quién. El punto de partida auditado de toda ejecución. |
| Grafo | La plantilla de un plan compilada a un grafo tipado de nodos (graphs y graph_nodes), validado por el servidor antes de existir. |
| Operation | La unidad de trabajo con contrato: inputs tipados → output + costo. 75 pares id@versión en el catálogo (71 ids distintos), al 24-oct-2026. |
| Corrida | Una ejecución concreta del grafo (runs), con su acta de eventos (run_events) y un work item por cada nodo despachado, con su costo real. Reemplazó a la trace del motor viejo. |
| Artifact | Lo producido (digest, brief, video…), direccionable por contenido, con máquina de estados. |
| Claim | Un hecho tipado (sujeto, predicado, objeto) con provenance: el nodo que lo produjo. La memoria del equipo, consultable con SQL. |
| Human gate | La compuerta: la corrida queda en awaiting_human hasta que una persona decide en la app. El plazo es de 72 h y, si vence, el gate falla: nunca se auto aprueba. |
| SuperSkill | La palabra de producto para un flujo empaquetado: de fábrica o promovido por el usuario. |
"No te escondemos en una esquina inofensiva: te damos trabajo real dentro de las mismas barandas que le pusimos a la IA. Si la arquitectura contiene a un modelo impredecible, te contiene a vos, y por eso desde la semana uno tu trabajo cuenta."