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. Vas a escribir los tuyos igual.
Un server entero en una pantalla. Notá el idleTimeout: 120 y preguntate por qué existe — es una cicatriz real: el default de Bun (10s) mataba el streaming del chat cuando el modelo razonaba en silencio.
Una ventana deslizante pura con reloj inyectable. Es la clase magistral de "cómo hacer testeable algo que depende del tiempo".
Un Plan es un grafo tipado de pasos: quién firma cada uno, qué reintentos tiene, dónde está la compuerta humana. Acá entendés qué ES el trabajo en este sistema.
El catálogo: 17 operations, 16 con handler. La que falta — human_gate.approve — no es un olvido: la ejecuta el propio executor suspendiendo el workflow. Cuando entiendas por qué, entendiste la arquitectura.
assertHumanGatePresent: la gobernanza escrita como código. Ningún plan sin aprobación humana terminal puede ejecutarse — ni los de fábrica, ni los que compone la IA.
El ÚNICO lugar donde el LLM "diseña" — y por eso el más vigilado: whitelist, grafo sin ciclos, tope de pasos, costo calculado por el servidor. 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 fail-closed (error al leer = no autorizado). Mirá también el doble candado del bypass de tests (dev && CI).
La write-queue: por qué dos escrituras del estado del usuario jamás se pisan, y el revert compare-and-swap. Todo estado del usuario pasa por acá — nunca por un fetch directo.
El modelo de datos ES el producto: intents → plans → traces → artifacts/claims con provenance obligatoria. Leé los comentarios SQL — explican cada porqué.
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): id versionado (tuop.algo@1.0.0), inputs y output tipados. Mirá cómo lo hace audience.load — la operation pura más simple del catálogo.apps/api/src/inngest/operations/).operations/index.ts con registerOperation.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.El mock de módulos de Bun es GLOBAL: stubear exports de más pisó los reales y rompió 6 tests de streaming de otro archivo. Costó un review encontrarlo.| Término | Qué es |
|---|---|
| Intent | El pedido por escrito: qué quiere lograr quién. El punto de partida auditado de toda ejecución. |
| Plan | El Intent compilado a un grafo tipado de pasos, validado por el servidor antes de existir. |
| Operation | La unidad de trabajo con contrato: inputs tipados → output + costo. 17 en el catálogo. |
| Trace | Una ejecución concreta de un plan, paso a paso, con costo real por step. |
| Artifact | Lo producido (digest, brief, video…), direccionable por contenido, con máquina de estados. |
| Claim | Un hecho tipado (sujeto·predicado·objeto) con provenance. La memoria del equipo, consultable con SQL. |
| Human gate | La compuerta: el workflow se SUSPENDE hasta 24h esperando a un humano. La decisión se vuelve claims. |
| 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."