Parity Gate¶

Gate obligatorio que bloquea PRs y deploys si el flow-engine v2 no reproduce exactamente el comportamiento de los 21 flows legacy V1. Decisión: ADR-0012.

Cómo funciona¶

flowchart LR
    L[21 flows legacy JSON] --> T[flow-transpiler]
    T --> V[Flow v2 JSON]
    V --> E[flow-engine v2
run en LocalStack]
    F[60+ fixtures
input → expected output] --> E
    E --> C{match?}
    C -- sí --> P[PASS]
    C -- no --> X[FAIL: PR bloqueado]

Comando¶

npm run test:parity --workspace=@zengine/flow-engine

Corre en CI como job parity-gate (bloqueante). Local funciona sin LocalStack si se mockea el cliente DDB (PARITY_USE_MEMORY=1).

Estructura de fixtures¶

services/flow-engine/tests/parity/
  flows-legacy/
    iplacex-bienvenida.json         # JSON original V1
    iplacex-soporte-l1.json
    ...
  scenarios/
    iplacex-bienvenida/
      01-saludo-feliz.json          # { input, expectedReplies, expectedContext }
      02-fallback.json
      ...

Cada scenario es:

{
  "input": { "text": "Hola" },
  "initialContext": { "user": { "firstName": "Cristian" } },
  "expected": {
    "replies": [{ "author": "bot", "text": "Hola Cristian, ¿en qué te ayudo?" }],
    "context": { "user": { "firstName": "Cristian" } },
    "currentStep": "router"
  }
}

Cómo agregar un fixture¶

1. Localizar el flow legacy: legacy/flows/<nombre>.json.
2. Crear scenario con input real (idealmente capturado de logs prod).
3. Correr el transpiler manualmente para generar el v2:

npx zen-transpile legacy/flows/<nombre>.json > services/flow-engine/tests/parity/flows-legacy/<nombre>.json

1. Correr npm run test:parity. Si falla, decide:
2. Bug en transpiler → fix + nuevo test unitario.
3. Bug en flow-engine v2 → fix.
4. Cambio intencional → ADR + actualizar expected.

Evolución del transpiler¶

packages/flow-transpiler cubre los step types V1:

Cualquier step no listado falla explícito con mensaje útil (UnsupportedLegacyStepError).

Criterio de cutover¶

ADR-0012 §Decisión: cutover al engine v2 requiere:

• 100% scenarios pasan.
• ≥60 scenarios cubriendo los 21 flows.
• Sin diferencias semánticas en los últimos 14 días de runs CI.