Scenario format v1

Source of truth: LILA_MODELER_ESTRUCTURA.md, section 6 ("Scenario format v1") and ADR-015. This document is the normative specification for *.scenario.json; when it differs from the structure document, the structure document prevails and this file is corrected.

Ticket: LILA-004 (E0 · M0). It is written before the engine. Implemented by packages/engine/src/scenario.ts (zod + JSON Schema) and resolveScenario().

1. What is a scenario

A scenario is a JSON file separate from the .bpmn that holds a model's simulation parameters: when and how long it runs, which calendars and resources exist, and which parameters each diagram element carries, keyed by the BPMN id (ADR-012: the id is the only key; never the name).

Why separate, and why a custom JSON format (ADR-015): N scenarios per diagram; git diffs without DI-coordinate noise; patchable by an agent as elements["Task_1"].processingTime.mean = 400; migrates 1:1 to a jsonb column. The vocabulary (field and distribution names) follows BPSim 2.0 so that edge adapters stay trivial, but BPSim and qbp are not the canonical format.

What it is not: it carries no geometry, element names, or documentation — that lives in the .bpmn (ADR-013). It carries no results — that is RESULTS_FORMAT.md.

Naming convention: <name>.scenario.json, alongside the project's .bpmn (examples/pedido/as-is.scenario.json).

2. Structure

2.1 Root

¹ Required in the resolved scenario (after applying extends), not in every file: a child that declares extends inherits model and run from the parent.

Unknown keys are not accepted at the root (strict): a misspelled field is an error, not a silent pass.

2.2 run

² At least one of run.duration or a triggerCount on a start in elements (rule R6). If both are present, whichever occurs first wins.

Runtime work protection (#368)

run.duration limits simulated time, not the amount of work at one instant. R-TOK-7 in SEMANTICS.md independently limits effective events per case and instant, including zero-duration timers, and aborts with E-LIMITE-SIN-AVANCE when exceeded. The budget is max(100_000, 1_024 × (IR nodes + IR flows)), resets on time advancement, and is not a scenario field. Exceptionally expensive finite cases can exceed it. Timer defaults and R-DEG-3 are unchanged; event-gateway branches without a time still never fire.

2.3 calendars

Map key → { intervals: [...] }. The key is the identifier cited by resources[*].calendar and elements[*].calendar. The key default is the calendar taken by every pool that does not declare its own (R-CAL-10); elements do not inherit it.

Each interval carries exactly one day selector: days, monthDays, monthWeekdays or dates (R18). A calendar can mix them with several intervals.

"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"]
  }
}

Semantics (ADR-016): a weekly pattern relative to run.start; a task only starts within its effective calendar — the intersection of its pools' calendars with its own, R-CAL-4 — and its processingTime consumes only calendar time (it pauses when the shift closes, resumes when it opens); closed time is reported as offHoursWait, separate from resourceWait; utilization is computed over the time available according to the calendar. Overlapping intervals within the same calendar are merged (union, not sum). Monthly and annual recurrence and holidays are read in run.start's offset too (R-CAL-12 … R-CAL-14). No DST and no own timezone in v1 (§ 4, R-CAL-15).

2.4 resources

Map key → pool. The key is the one cited by elements[*].resources[].ref.

Queue: FIFO per pool, ordered by enablement instant, ties broken by seq.

Shift-based capacity (LILA-164). The same role can have a different headcount per shift — Bizagi Modeler's level-4 example: 3 day nurses and 1 night nurse. That is one pool with per-interval capacity, not one pool per shift:

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

Semantics (R-CAL-11 in SEMANTICS.md, §12):

• the pool is open whenever any of its calendars is (union); if the shifts cover 24 h, the pool is a 24×7 and no task has offHoursWait;
• capacity at t is the sum of the capacity_i whose calendar_i are open at t. Two overlapping calendars add up (unlike intervals within the same calendar, which are merged): [{ "dia": 2 }, { "24x7": 1 }] gives 3 units during the day and 1 at night, because they are two distinct groups of units of the same role;
• when a slot closes, tasks in progress are not interrupted: the pool can temporarily run above its capacity until they finish (same rule as R-REC-7);
• a task's quantity is validated against the weekly maximum, not the declared sum: 3 + 1 units in disjoint shifts are never 4 simultaneous units;
• utilization is integrated slot by slot: busyTime / Σᵢ (capacityᵢ × openTimeᵢ) over the measurement window (R-CAL-9).

The numeric form is the single-slot case: { "capacity": 3, "calendar": "dia" } and { "capacity": [{ "calendar": "dia", "capacity": 3 }] } produce exactly the same result.

2.5 elements

Map BPMN id → parameters. The keys are diagram ids: nodes (Task_…, StartEvent_…, Timer_…) and sequence flows (Flow_…).

Assigning a whole lane: the web panel can fill resources for every task of a lane in one action (resources section, "Assign lane"). It is a bulk edit of this same per-task field — the lane is a label of the diagram (docs/SEMANTICS.md § 2) and is never stored in the scenario — and tasks that already have resources are listed and require confirmation before being replaced.

Note on absent elements: a diagram element that does not appear in elements is valid and takes its defaults (a task with no time or resources, a flow with an even split). elements is a map of exceptions, not a mandatory mirror of the model.

3. Distributions

Object { "type": "...", <named parameters> }. Named parameters, never positional (ADR-015: this is what rules out Prosimos's scipy-style API). All values in seconds when the distribution describes a time. These are the 13 from BPSim 2.0 plus the constant; user is the empirical one.

Any type outside this list is a validation error with "not supported" text (ADR-021). Any extra parameter inside a distribution is also an error (strict object): {"type":"normal","mean":60,"stddev":10} fails citing stddev.

4. Reserved fields

These fields are in the schema (they are syntactically accepted, documented, and do not break a file written today), but the v1 engine rejects them with an explicit error when resolving the scenario. They are never ignored silently (ADR-021).

holidays was on this list until #82 implemented it (§ 2.3, R-CAL-14).

Error text: the same pattern as the rest of the "not supported" errors, citing the field and the element's id.

5. Validation rules

The first six are taken verbatim from the structure document; the rest are derived from section 6 and the cited ADRs.

Errors vs. warnings: an error prevents simulation; a warning travels in the RunResult's warnings[] and is printed in the CLI. A field applied to an element type that does not accept it (R4, R5, R14) is an error, not a warning: it is almost always a wrong id.

Schema defects (the ones zod catches before R3–R17: wrong type, out of range, unknown key, nonexistent variant) come out in Spanish and cite the path — run.warmup: debe ser ≥ 0 —, with the same text in the CLI, in the MCP, and in the scenario panel. The catalog is erroresEnEspanol in packages/engine/src/scenario.ts, and parseScenario is the only gate that applies it; whatever that map does not translate falls through to zod's es locale. One exception: the unknown-key error appears in the CLI with the § 17 text (E-CLAVE-DESCONOCIDA: clave no reconocida por el esquema: …, produced by schemaIssueLines), because the § 17 catalog overrides the map. This document's own messages (R8, R11, R13, E-CAL-VACIO…) are written by the schema and override the map. Semantic errors and warnings are a different matter: they are defined by the § 17 catalog in docs/SEMANTICS.md.

6. extends semantics

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

• Deep merge: the child is applied onto the parent object by object. Anything not mentioned is inherited intact.
• null deletes the key: {"resources": {"horno": null}} removes the horno pool from the resolved scenario.
• Arrays are replaced whole, not merged element by element: a task's resources: [...], a calendar's intervals: [...], and a user distribution's points: [...] are substituted in full. It is the only predictable semantics for a list without keys.
• Chains allowed: A extends B extends C. It is resolved from the root down (C, then B, then A).
• Cycles rejected: any cycle in the chain is an error, citing the files involved.
• Paths relative to the child's file, not to the working directory. model is also resolved relative to the file where it is written.
• __proto__, constructor, and prototype are ignored: in JavaScript these are not ordinary keys (they write onto the object's prototype), so the merge skips them in any object at any depth, without warning. No field in § 2 is named this way; inside an array they are caught by the schema as E-CLAVE-DESCONOCIDA (LILA-204).
• Validation (§ 5) applies to the resolved scenario, not to each file separately: that is why a delta may omit model and run.

7. Examples

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

Copied verbatim from the structure document, section 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 as a delta

Copied verbatim from the structure document, section 6:

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

(deep merge; null deletes; chains allowed; cycles rejected)

Resolved, it is identical to the AS-IS except for resources.cajero.capacity = 3 — which is exactly M0's acceptance test: Scenario.parse(to-be) resolves extends to an object equal to the AS-IS except for capacity = 3.

7.3 Checking the examples against the rules

The AS-IS satisfies every rule in § 5 (examples/pedido/model.bpmn must contain the seven cited ids):

Defaults exercised by the example: cocinero with no fixedCost ⇒ 0; horno with no calendar ⇒ 24×7; Task_Preparar and Task_Revisar with resources and no quantity ⇒ 1; Timer_Reposo with no resources ⇒ pure delay; Task_TomarPedido with no selection ⇒ and.

8. Field mapping: Lila ↔ BPSim 2.0 ↔ qbp ↔ Bizagi Modeler

What this is for: adapters live at the edges and are only written when a consumer appears (ADR-015) — qbp import (Prosimos/Simod fixtures), .bpsim export/import for Sparx EA, and reading Bizagi Modeler's published examples. This table is the contract for those adapters. — = no equivalent.

In bold, the four mappings already fixed in the structure document.

† To be verified against the BPSim 2.0 XSD when writing the .bpsim adapter. The row is documented as intent, not as a verified fact.

Known limitations of the external formats, which is why none of them serves as canonical (ADR-015):

• BPSim 2.0 has been frozen since 2016, has no open-source tooling, and, embedded in the .bpmn, mixes layout with parameters.
• qbp supports a single scenario per file and one resource per task: selection, quantity > 1, and multiple scenarios have nowhere to go. Import is an acceptable degradation; export loses information and must warn.
• Bizagi Modeler does not export simulation parameters (verified against 5 real files: only colors travel in bizagi:). The Bizagi Modeler column is there to name things the same way its UI does, not to exchange files.
• Prosimos uses positional scipy-style parameters and carries no license: it is only used as a numeric oracle during development, never as a format.

9. Version changes

version is an integer. v1 grows additively: new optional fields and reserved fields that become implemented do not bump the version. It moves to 2 only if the meaning of an existing field changes or one disappears. The engine rejects a version it does not recognize; it never guesses.

Changes already applied within v1:

• Per-interval resources[*].capacity (LILA-164, § 2.4). version stays at 1: it is a widening of the type, not a change of meaning. Every earlier v1 scenario remains valid and produces the same result byte for byte, because the integer form is the single-slot case. A scenario using the new form is not understood by an older engine: the strict schema rejects it with a type error, which is the correct degradation (never guess).