[F4-02] Orquestador del pipeline: grafo de pasos y máquina de estados #57

Fase: F4 · Tamaño: L · Depende de: #54 (F4-01), #46 (F3-03), #47 (F3-04)
Decisiones: D-05 y D-06 en #1

Objetivo

Ejecutar los pasos del pipeline en el orden correcto, en paralelo cuando se pueda, con Mongo como fuente de verdad, de forma que un reinicio del worker nunca pierda ni repita trabajo ya hecho.

Grafo de la v1

seed → direction → story → package → ttsScript? → voice
story → visualTokens
voice → music                       (proveedor o biblioteca)
voice → storyboard → imagePrompts → image[1..N]   (fan-out, un trabajo por escena)
voice + music + image[*] → assemble (slideshow + póster)

Alcance

• advance(projectId) se ejecuta al terminar cada paso: carga el proyecto, calcula los pasos ejecutables (dependencias en succeeded, propio en pending), los pasa a queued con un findOneAndUpdate condicionado y los encola. El jobId de BullMQ es ${projectId}:${step}[:${n}]:${attempt} (evita duplicados).
• Estados del proyecto: queued → running → completed | failed | cancelled. Estados de paso y escena: pending → queued → running → succeeded | failed | skipped | cancelled, con attempts, startedAt, finishedAt, progress, error { code, message, retryable }.
• Cada paso guarda su salida (texto en el proyecto, binarios como Asset) antes de marcarse succeeded.
• El worker resuelve los proveedores del proyecto descifrando las credenciales de su modelSelection justo antes de usarlas.
• Cada cambio incrementa project.rev y publica un evento en Redis project:<id> (lo consume SSE, [F4-11] Progreso en tiempo real por SSE #68).
• Pasos con resultado vacío o no aplicable se marcan skipped (p. ej. ttsScript si el modelo TTS no admite indicaciones).

Criterios de aceptación

• Test con fake: un proyecto pasa de queued a completed y todos sus pasos quedan succeeded o skipped.
• Test: voice y visualTokens se ejecutan en paralelo (sus intervalos de ejecución se solapan).
• Test: matar el worker a mitad y arrancarlo de nuevo completa el proyecto sin volver a ejecutar los pasos ya succeeded (contador de llamadas al proveedor).
• Test: llamar a advance dos veces a la vez no encola el mismo paso dos veces.
• Test: cada transición incrementa rev y publica un evento.