Formato de escenario v1

Fuente de verdad: LILA_MODELER_ESTRUCTURA.md, sección 6 ("Formato de escenario v1") y ADR-015. Este documento es la especificación normativa de *.scenario.json; cuando difiera del documento de estructura, manda el documento de estructura y este archivo se corrige.

Ticket: LILA-004 (E0 · M0). Se escribe antes del motor. Lo implementan packages/engine/src/scenario.ts (zod + JSON Schema) y resolveScenario().

1. Qué es un escenario

Un escenario es un archivo JSON separado del .bpmn que contiene los parámetros de simulación de un modelo: cuándo y cuánto corre, qué calendarios y recursos existen, y qué parámetros lleva cada elemento del diagrama, keyed por el id BPMN (ADR-012: el id es la única clave; nunca el nombre).

Por qué separado y por qué JSON propio (ADR-015): N escenarios por diagrama; diffs de git sin ruido de coordenadas DI; parcheable por un agente como elements["Task_1"].processingTime.mean = 400; migra 1:1 a una columna jsonb. El vocabulario (nombres de campo y de distribución) sigue a BPSim 2.0 para que los adaptadores de los bordes sean triviales, pero BPSim y qbp no son el formato canónico.

Qué no es: no lleva geometría, ni nombres de elementos, ni documentación — eso vive en el .bpmn (ADR-013). No lleva resultados — eso es RESULTS_FORMAT.md.

Convención de nombre: <nombre>.scenario.json, junto al .bpmn del proyecto (examples/pedido/as-is.scenario.json).

2. Estructura

2.1 Raíz

¹ Obligatorio en el escenario resuelto (después de aplicar extends), no en cada archivo: un hijo que declara extends hereda model y run del padre.

No se aceptan claves desconocidas en la raíz (strict): un campo mal escrito es un error, no un silencio.

2.2 run

² Al menos uno de run.duration o un triggerCount en un start de elements (regla R6). Si están los dos, gana lo primero que ocurra.

Protección del trabajo durante la ejecución (#368)

run.duration limita el tiempo simulado, no el trabajo en un instante. R-TOK-7 de SEMANTICS.md limita por separado los eventos efectivos por caso e instante, incluidos los temporizadores de duración cero, y aborta con E-LIMITE-SIN-AVANCE al superarlo. El presupuesto es max(100_000, 1_024 × (nodos IR + flujos IR)), se reinicia al avanzar el tiempo y no es un campo del escenario. Un caso finito excepcionalmente costoso puede superarlo. Los valores predeterminados y R-DEG-3 no cambian; las ramas de gateway de eventos sin tiempo siguen sin dispararse.

2.3 calendars

Mapa clave → { intervals: [...] }. La clave es el identificador que citan resources[*].calendar y elements[*].calendar. La clave default es el calendario que toma todo pool que no declare el suyo (R-CAL-10); los elementos no la heredan.

Cada intervalo lleva exactamente un selector de días: days, monthDays, monthWeekdays o dates (R18). Un calendario los mezcla con varios intervalos.

"calendars": {
  "oficina": {
    "intervals": [
      { "days": ["MON", "TUE", "WED", "THU", "FRI"], "from": "09:00", "to": "18:00" },
      { "monthWeekdays": [{ "nth": -1, "day": "SAT" }], "from": "09:00", "to": "13:00" }
    ],
    "holidays": ["01-01", "12-25", "2026-11-02"]
  }
}

Semántica (ADR-016): patrón semanal relativo a run.start; una tarea solo arranca dentro de su calendario efectivo —la intersección de los de sus pools con el suyo propio, R-CAL-4— y su processingTime consume solo tiempo de calendario (se pausa al cerrar el turno, reanuda al abrir); el tiempo cerrado se reporta como offHoursWait, separado de resourceWait; la utilización se calcula sobre el tiempo disponible según calendario. Intervalos solapados dentro del mismo calendario se unen (unión, no suma). La recurrencia mensual y anual y los festivos también se leen en el offset de run.start (R-CAL-12 … R-CAL-14). Sin DST ni zona horaria propia en v1 (§ 4, R-CAL-15).

2.4 resources

Mapa clave → pool. La clave es la que citan elements[*].resources[].ref.

Cola: FIFO por pool, ordenada por instante de habilitación, empate por seq.

Capacidad por turno (LILA-164). Un mismo rol puede tener distinta cantidad según el turno —el caso del nivel 4 de Bizagi: 3 enfermeras de día y 1 de noche—. Eso es un pool con capacity por intervalos, no un pool por turno:

"resources": {
  "enfermera": {
    "name": "Nurse", "type": "role", "fixedCost": 5,
    "capacity": [
      { "calendar": "dia",   "capacity": 3 },
      { "calendar": "noche", "capacity": 1 }
    ]
  }
}

Semántica (R-CAL-11 de SEMANTICS.md, §12):

• el pool está abierto cuando lo está cualquiera de sus calendarios (unión); si los turnos cubren las 24 h, el pool es un 24×7 y ninguna tarea tiene offHoursWait;
• la capacidad en t es la suma de los capacity_i cuyos calendar_i están abiertos en t. Dos calendarios que se solapan suman (a diferencia de los intervalos de un mismo calendario, que se unen): [{ "dia": 2 }, { "24x7": 1 }] da 3 unidades de día y 1 de noche, porque son dos grupos distintos de unidades del mismo rol;
• al cerrar un tramo, las tareas en curso no se interrumpen: el pool puede quedar temporalmente por encima de su capacidad hasta que terminen (misma regla que R-REC-7);
• quantity de una tarea se valida contra el máximo de la semana, no contra la suma declarada: 3 + 1 unidades en turnos disjuntos nunca son 4 simultáneas;
• la utilización se integra tramo a tramo: busyTime / Σᵢ (capacityᵢ × openTimeᵢ) sobre la ventana de medida (R-CAL-9).

La forma numérica es el caso de un solo tramo: { "capacity": 3, "calendar": "dia" } y { "capacity": [{ "calendar": "dia", "capacity": 3 }] } producen exactamente el mismo resultado.

2.5 elements

Mapa id BPMN → parámetros. Las claves son ids del diagrama: nodos (Task_…, StartEvent_…, Timer_…) y sequence flows (Flow_…).

Asignar un carril entero: el panel web puede rellenar resources en todas las tareas de un carril en una sola acción (sección de recursos, «Asignar carril»). Es una edición en bloque de este mismo campo por tarea —el carril es una etiqueta del diagrama (docs/SEMANTICS.md § 2) y no se guarda nunca en el escenario— y las tareas que ya tienen resources se listan y piden confirmación antes de reemplazarlas.

Nota sobre elementos ausentes: un elemento del diagrama que no aparece en elements es válido y toma sus defaults (tarea sin tiempo ni recursos, flujo con reparto equitativo). elements es un mapa de excepciones, no un espejo obligatorio del modelo.

3. Distribuciones

Objeto { "type": "...", <parámetros nombrados> }. Parámetros nombrados, nunca posicionales (ADR-015: eso es lo que descarta el estilo scipy de Prosimos). Todos los valores en segundos cuando la distribución describe un tiempo. Son las 13 de BPSim 2.0 más la constante; user es la empírica.

Cualquier type fuera de esta lista es error de validación con el texto de "no soportado" (ADR-021). Cualquier parámetro sobrante dentro de una distribución también es error (objeto estricto): {"type":"normal","mean":60,"stddev":10} falla citando stddev.

4. Campos reservados

Estos campos están en el esquema (se aceptan sintácticamente, se documentan, no rompen un archivo escrito hoy) pero el motor v1 los rechaza con un error explícito al resolver el escenario. Nunca se ignoran en silencio (ADR-021).

holidays estuvo en esta lista hasta que #82 lo implementó (§ 2.3, R-CAL-14).

Texto del error: el mismo patrón que el resto de "no soportado", citando el campo y el id del elemento.

5. Reglas de validación

Las seis primeras son literalmente las del documento de estructura; las demás se derivan de la sección 6 y de los ADR citados.

Errores vs. warnings: un error impide simular; un warning viaja en warnings[] del RunResult y se imprime en la CLI. Un campo aplicado a un tipo de elemento que no lo admite (R4, R5, R14) es error, no warning: es casi siempre un id equivocado.

Los defectos del esquema (los que caza zod antes de R3–R17: tipo equivocado, fuera de rango, clave desconocida, variante inexistente) salen en español y citan la ruta — run.warmup: debe ser ≥ 0 —, con el mismo texto en la CLI, en el MCP y en el panel de escenario. El catálogo es erroresEnEspanol en packages/engine/src/scenario.ts, y parseScenario es la única puerta que lo aplica; lo que ese mapa no traduce cae en la locale es de zod. Única excepción: la clave desconocida sale en la CLI con el texto de § 17 (E-CLAVE-DESCONOCIDA: clave no reconocida por el esquema: …, que pone schemaIssueLines), porque el catálogo de § 17 manda sobre el mapa. Los mensajes propios de este documento (R8, R11, R13, E-CAL-VACIO…) los escribe el esquema y mandan sobre el mapa. Los errores y avisos semánticos son otra cosa: los define el catálogo § 17 de docs/SEMANTICS.md.

6. Semántica de extends

{ "extends": "as-is.scenario.json", "resources": { "cajero": { "capacity": 3 } } }

• Merge profundo: el hijo se aplica sobre el padre objeto a objeto. Lo no mencionado se hereda intacto.
• null borra la clave: {"resources": {"horno": null}} elimina el pool horno del escenario resuelto.
• Los arrays se reemplazan enteros, no se fusionan elemento a elemento: resources: [...] de una tarea, intervals: [...] de un calendario y points: [...] de una user se sustituyen completos. Es la única semántica predecible para una lista sin claves.
• Cadenas permitidas: A extends B extends C. Se resuelve de la raíz hacia abajo (C, luego B, luego A).
• Ciclos rechazados: cualquier ciclo en la cadena es error, citando los archivos implicados.
• Rutas relativas al archivo del hijo, no al directorio de trabajo. model también se resuelve relativo al archivo donde está escrito.
• __proto__, constructor y prototype se ignoran: en JavaScript no son claves normales (escriben en el prototipo del objeto), así que la fusión las salta en cualquier objeto y a cualquier profundidad, sin avisar. Ningún campo del § 2 se llama así; dentro de un array las caza el esquema como E-CLAVE-DESCONOCIDA (LILA-204).
• La validación (§ 5) se aplica al escenario resuelto, no a cada archivo por separado: por eso un delta puede no traer model ni run.

7. Ejemplos

7.1 AS-IS (examples/pedido/as-is.scenario.json)

Copiado tal cual del documento de estructura, sección 6.

{
  "$schema": "https://lila-modeler.org/schema/scenario/1.json",
  "version": 1,
  "name": "AS-IS",
  "description": "Operación actual, 2 cajeros y 3 cocineros",
  "model": "model.bpmn",
  "run": {
    "start": "2026-09-07T08:00:00-06:00",
    "duration": 2592000,
    "warmup": 3600,
    "replications": 30,
    "seed": 42,
    "baseTimeUnit": "min",
    "currency": "MXN"
  },
  "calendars": {
    "oficina": { "intervals": [ { "days": ["MON","TUE","WED","THU","FRI"], "from": "09:00", "to": "18:00" } ] }
  },
  "resources": {
    "cajero":   { "name": "Cajero",   "type": "role",      "capacity": 2, "costPerHour": 220, "fixedCost": 0, "calendar": "oficina" },
    "cocinero": { "name": "Cocinero", "type": "role",      "capacity": 3, "costPerHour": 180, "calendar": "oficina" },
    "horno":    { "name": "Horno",    "type": "equipment", "capacity": 1 }
  },
  "elements": {
    "StartEvent_Pedido": { "interTriggerTimer": { "type": "exponential", "mean": 240 }, "triggerCount": 10000, "calendar": "oficina" },
    "Task_TomarPedido":  { "processingTime": { "type": "triangular", "min": 60, "mode": 120, "max": 300 },
                           "resources": [ { "ref": "cajero", "quantity": 1 } ], "fixedCost": 2.5 },
    "Task_Preparar":     { "processingTime": { "type": "normal", "mean": 480, "sd": 90 },
                           "resources": [ { "ref": "cocinero" }, { "ref": "horno" } ], "selection": "and" },
    "Task_Revisar":      { "processingTime": { "type": "constant", "value": 90 },
                           "resources": [ { "ref": "cajero" }, { "ref": "cocinero" } ], "selection": "or" },
    "Timer_Reposo":      { "processingTime": { "type": "constant", "value": 600 } },
    "Flow_Aprobado":     { "probability": 0.78 },
    "Flow_Rechazado":    { "probability": 0.22 }
  }
}

7.2 TO-BE como delta

Copiado tal cual del documento de estructura, sección 6:

{ "version": 1, "name": "TO-BE 3 cajeros", "extends": "as-is.scenario.json", "resources": { "cajero": { "capacity": 3 } } }

(merge profundo; null borra; cadenas permitidas; ciclos rechazados)

Resuelto, es idéntico al AS-IS salvo resources.cajero.capacity = 3 — que es exactamente la prueba de aceptación de M0: Scenario.parse(to-be) resuelve extends a un objeto igual al AS-IS salvo capacity = 3.

7.3 Verificación de los ejemplos contra las reglas

El AS-IS pasa cada regla de la § 5 (examples/pedido/model.bpmn debe contener los siete ids citados):

Defaults que ejercita el ejemplo: cocinero sin fixedCost ⇒ 0; horno sin calendar ⇒ 24×7; Task_Preparar y Task_Revisar con resources sin quantity ⇒ 1; Timer_Reposo sin resources ⇒ retardo puro; Task_TomarPedido sin selection ⇒ and.

8. Mapeo campo ↔ BPSim 2.0 ↔ qbp ↔ Bizagi

Para qué sirve: los adaptadores viven en los bordes y solo se escriben cuando aparece un consumidor (ADR-015) — import de qbp (fixtures de Prosimos/Simod), export/import de .bpsim para Sparx EA, y lectura de los ejemplos publicados de Bizagi. Esta tabla es el contrato de esos adaptadores. — = sin equivalente.

En negrita, los cuatro mapeos ya fijados en el documento de estructura.

† Por verificar contra el XSD de BPSim 2.0 al escribir el adaptador .bpsim. La fila se documenta como intención, no como hecho comprobado.

Limitaciones conocidas de los formatos ajenos, que hacen que ninguno sirva como canónico (ADR-015):

• BPSim 2.0 está congelado desde 2016, no tiene tooling open source y, embebido en el .bpmn, mezcla layout con parámetros.
• qbp admite un solo escenario por archivo y un recurso por tarea: selection, quantity > 1 y varios escenarios no tienen destino. La importación es una degradación aceptable; la exportación pierde información y debe avisar.
• Bizagi no exporta parámetros de simulación (verificado en 5 archivos reales: en bizagi: solo viajan colores). La columna Bizagi sirve para nombrar las cosas igual que su UI, no para intercambiar archivos.
• Prosimos usa parámetros posicionales de scipy y no tiene licencia: solo se usa como oráculo numérico en desarrollo, nunca como formato.

9. Cambios de versión

version es un entero. v1 crece de forma aditiva: campos nuevos opcionales y campos reservados que pasan a implementarse no suben la versión. Se sube a 2 solo si cambia el significado de un campo existente o desaparece uno. El motor rechaza una version que no conoce; nunca adivina.

Cambios ya aplicados dentro de v1:

• resources[*].capacity por intervalos (LILA-164, § 2.4). version sigue en 1: es un ensanchamiento del tipo, no un cambio de significado. Todo escenario v1 anterior sigue siendo válido y da el mismo resultado byte a byte, porque el entero es el caso de un solo tramo. Un escenario que use la forma nueva no lo entiende un motor anterior: el esquema estricto lo rechaza con un error de tipo, que es la degradación correcta (no adivinar).