Simulate a Simulator graph

The simulation engine runs inside this MCP server. It reads a layer (actors, links, account values), runs behaviour rules in model time for each scenario and returns metrics. It never writes to Simulator: the source layer is only read.

Format of models and scenarios: $CLAUDE_PLUGIN_ROOT/docs/simulation/model-format.md — read it before writing a model. Worked examples: $CLAUDE_PLUGIN_ROOT/docs/simulation/examples/.

1. Pick the graph — always ask

If a tool answers "not authenticated", call login and repeat the call.

• If the UI context has activeLayer, offer it first; otherwise help the user find a layer (getLayerActorsPaginated, layerStats) and confirm which one.
• Look at what is there before modelling: simulationSnapshot(layerId, period?) writes <layerId>.sim.yaml with every actor, link and account value the simulation will see.
• Account values that accumulate over time (bills, turnover) need period (e.g. 30d): values become the turnover of the last period. Check for accounts that are breakdowns of the same total (by service, region, operation): summing them counts one bill many times.

2. Write the model with the user

Ask only what changes the result: which actors behave and how, what the scenarios change, the horizon, what to measure. Show the rules in plain words before running, and label assumptions (durations, probabilities, growth rates) as assumptions.

A model is YAML (spec §5): value_types, refs, params, horizon, initial_events, behaviors.<actor type>.<event>: [actions], metrics, goals, optional helper actors (people or resources that are not on the graph). Actor types are form titles.

Rules of thumb:

• Money and other quantities that only move between actors: conserved: true and transfer. Things that only grow (hours worked, missed sales): not conserved, add.
• Capacity (people, machines, slots): an integer conserved account on a resource actor plus enqueue / release.
• Processes drawn as graphs: steps are actors, transitions are links; an application walks with pick(where(actor(self.at).children(), …)) (see examples/process_flow).
• Never write a key named on: (YAML reads it as true); use actor:.

3. Check, then run

simulationCheck(model, scenarios, layerId | graphPath)

simulationRun checks the model too and refuses a model with errors. Warnings (an event nobody handles, a param typo) usually mean the model does not do what the user thinks.

simulationRun(model, scenarios, layerId, period?, scenario?, runs?, goals?, logEvents?)

• The model has randomness (rand(), pick, chance, a decide without a rule): never report a single run. Use runs: 100 and report the median, the 10–90 % range and the share of runs meeting each goal.
• These numbers cover completed runs only (runs completed/total in the table). When runs failed or stopped before the horizon (stopped_by_time, stopped_by_limit), say how many and why (the lines under the table): a scenario that stops early is not cheaper or faster, it is unfinished. Raise timeLimit or shorten the horizon rather than compare it.
• A warning that the snapshot was written by v2.9.0 means its numbers are text: re-take it with simulationSnapshot(layerId, overwrite: true) before trusting any result.
• No randomness: one run is exact; say so.
• logEvents: 30 returns the first processed events — use it to explain why a result happened.

4. Explain

• Lead with the answer, then the comparison table. Name the scenario and metric behind every number; separate results from assumptions.
• A range from runs is spread over the model's random outcomes, not a confidence interval for the real world.
• The engine computes the consequences of the rules exactly (decimal arithmetic, conserved totals checked on every step); whether the rules match reality is a separate question, best answered by comparing with history.