Stately Studio: diseñar en el lienzo y aterrizar en el repositorio

La primera reacción ante un editor visual de máquinas suele ser la sospecha de que se trata de una herramienta para quien no sabe escribir código, o de una capa de presentación sobre algo que se acabará tocando a mano de todas formas. Es una lectura razonable y equivocada. El estudio de Stately no edita una representación del sistema: edita el sistema, porque el objeto que manipula el lienzo y el objeto que interpreta tu aplicación son el mismo grafo de estados y transiciones expresado en dos sintaxis. Lo interesante no es que se pueda arrastrar un estado con el ratón, sino la condición técnica que hace que arrastrarlo produzca código que un ingeniero aceptaría en una revisión, y esa condición tiene nombre y vive en la API setup de XState v5.

El lienzo como editor del artefacto

El estudio ofrece cuatro capacidades que conviene separar mentalmente porque se usan en momentos distintos. La primera es la edición: crear estados, anidarlos, conectarlos con transiciones etiquetadas por evento, añadir guardas y acciones por nombre, marcar estados finales y regiones paralelas. La segunda es la simulación: entrar en un modo donde el diagrama se recorre haciendo clic sobre los eventos disponibles, con el estado activo resaltado, sin arrancar ninguna aplicación ni escribir una línea de interfaz. La tercera es el intercambio: importar código pegado, exportar a XState v5, a JSON o a imagen, y sincronizar con un repositorio. La cuarta es la colaboración: comentarios sobre el lienzo, versiones guardadas y bifurcaciones para explorar alternativas sin destruir la que ya se acordó.

La colaboración merece un comentario aparte porque se subestima. Poder bifurcar un modelo y proponer una variante sin destruir la acordada convierte una discusión de producto en algo parecido a una petición de cambio: hay una versión base, una propuesta, un lugar donde comentar y una decisión explícita de adoptar o descartar. Los desacuerdos sobre comportamiento que en un documento se resuelven por cansancio o por antigüedad, aquí se resuelven comparando dos modelos y recorriéndolos, que es un procedimiento con muchas menos aristas políticas.

De las cuatro, la que más cambia la forma de trabajar es la simulación, y por una razón económica. El coste de corregir una decisión de comportamiento crece con lo que se ha construido encima: cambiar una transición en el lienzo cuesta segundos, cambiarla cuando ya hay tres componentes, dos pruebas y una llamada al servidor colgando de ella cuesta una tarde y una discusión. Simular es adelantar el descubrimiento del error al momento en que es barato. Esta es la misma lógica del desplazamiento a la izquierda que se predica para las pruebas, aplicada un paso antes: no se prueba la implementación, se prueba la especificación.

Por qué este round trip sí funciona

La lección anterior dejó el diagnóstico del fracaso de las herramientas CASE: el round trip entre dos representaciones de expresividad desigual degenera en una fusión perpetua. La solución de XState v5 es no intentar la simetría. En lugar de traducir todo el código a diagrama y de vuelta, parte la máquina en dos mitades con dueños distintos. La mitad que el lienzo posee es el esqueleto: estados, jerarquía, transiciones, eventos, y los nombres de las acciones, guardas y actores. La mitad que el repositorio posee son las implementaciones: las funciones que esos nombres designan. setup es exactamente la costura entre ambas.

import { setup, assign, fromPromise } from 'xstate'

export const pago = setup({
  types: {
    context: {} as { intentos: number; error: string | null },
    events: {} as { type: 'PAGAR' } | { type: 'REINTENTAR' },
  },
  // Implementaciones: viven en el repositorio, el lienzo solo ve sus nombres.
  actions: {
    contarIntento: assign({ intentos: ({ context }) => context.intentos + 1 }),
    limpiarError: assign({ error: null }),
  },
  guards: {
    quedanIntentos: ({ context }) => context.intentos < 3,
  },
  actors: {
    cobrar: fromPromise(async () => {
      const res = await fetch('/api/cobro', { method: 'POST' })
      if (!res.ok) throw new Error('cobro rechazado')
      return res.json()
    }),
  },
}).createMachine({
  // Esqueleto: esto es lo que el lienzo dibuja y devuelve.
  id: 'pago',
  initial: 'listo',
  context: { intentos: 0, error: null },
  states: {
    listo: {
      on: { PAGAR: { target: 'cobrando', actions: 'contarIntento' } },
    },
    cobrando: {
      invoke: {
        src: 'cobrar',
        onDone: 'hecho',
        onError: [
          { target: 'fallido', guard: 'quedanIntentos' },
          { target: 'agotado' },
        ],
      },
    },
    fallido: { on: { REINTENTAR: { target: 'cobrando', actions: 'limpiarError' } } },
    hecho: { type: 'final' },
    agotado: { type: 'final' },
  },
})

Obsérvese que en el bloque de createMachine no hay una sola función: contarIntento, quedanIntentos y cobrar son cadenas de texto que apuntan a implementaciones declaradas arriba. Ese bloque es JSON con azúcar sintáctico, y por eso el lienzo puede leerlo, dibujarlo, dejar que alguien mueva una flecha y devolverlo sin haber tocado ni una línea de lógica. La asimetría que hundió al round trip de UML se resuelve no reduciéndola sino declarándola: hay una frontera explícita, cada lado tiene un dueño y la herramienta jamás cruza.

flowchart LR
A[Esqueleto en el repositorio] -->|importar o sincronizar| B[Lienzo del estudio]
B -->|editar y simular| B
B -->|exportar a XState v5| C[Esqueleto revisado]
C -->|revision de cambios| A
D[Implementaciones en setup] -.el lienzo nunca las toca.-> A

La consecuencia práctica es una regla de organización de archivos que conviene adoptar desde el primer día: el archivo de la máquina contiene el setup con implementaciones cortas y el createMachine con el esqueleto, y nada más. Sin componentes, sin utilidades, sin constantes de otra parte del dominio. Si las implementaciones crecen, se extraen a un módulo aparte y se importan; si necesitan depender del entorno —una implementación falsa en pruebas, otra real en producción— se dejan como referencias y se inyectan con el método provide en el punto de creación del actor. Cuanto más fina sea la capa de implementación dentro del archivo, más mecánico es aplicar lo que vuelve del lienzo.

La frontera y sus señales

Toda la propiedad descansa en que el esqueleto siga siendo serializable, y es fácil perforarlo sin darse cuenta. Cuatro señales indican que se ha cruzado la frontera y que alguna proyección acaba de morir en silencio.

Las dos últimas señales tienen remedios simples y vale la pena aplicarlos antes de que hagan daño. Contra los nombres técnicos, la convención de nombrar los estados con adjetivos o participios del dominio —revisando, expirado, pendiente de firma— y las acciones con verbos que un responsable de producto reconocería. Contra el ruido en las diferencias, pasar siempre el archivo por el formateador del proyecto tras pegar desde el lienzo, y tratar el bloque de createMachine como si fuera generado: no se reordena a mano por gusto estético, porque cada reordenación manual se pierde en la siguiente exportación.

Los tipos merecen una nota, porque son el punto donde más gente tropieza al adoptar el ciclo. El bloque types de setup declara la forma del contexto y la unión de eventos, y es código TypeScript, no dato: el lienzo no lo deduce ni lo mantiene. Cuando en el estudio se añade una transición con un evento nuevo, el código exportado lo referencia y el compilador protesta hasta que alguien amplía la unión a mano. Eso no es un defecto del ciclo, es la frontera funcionando: el modelo propone un evento nuevo y el sistema de tipos exige que se declare antes de aceptarlo. Conviene explicarlo antes de la primera exportación para que nadie interprete el error como un fallo de la herramienta.

Hay además una decisión de gobierno que ningún manual resuelve por ti: quién es la fuente de verdad cuando el estudio y el repositorio divergen. La respuesta que funciona en equipos de producto es que el repositorio siempre gana, y el estudio se trata como un espacio de trabajo desde el que se proponen cambios que entran por el mismo camino que cualquier otro código: una rama, una revisión, una fusión. La sincronización con el repositorio que ofrece el estudio se configura precisamente para eso. Invertir la jerarquía —que el estudio sea canónico y el repositorio un reflejo— parece más elegante y produce, sin excepción, la clase de conflictos que arruinaron el round trip de los años dos mil.