Config YAML Reference

A scenario is one YAML file at scenarios/<Name>/<Name>.yaml. The loader parses it in two stages — flexible raw types (Raw*, custom UnmarshalYAML) are converted into strongly-typed Config structures, with string names resolved to integer indices.

Top-level keys

Key	Purpose
`type`	The document discriminator, the literal `mock_machines_scenario` — how a reader tells the config from the other yamls in a scenario package (a `theme.yaml`, an OSI overlay), and what package discovery selects on. It has no bearing on the simulation: omitting it warns (A9) and everything still loads, deploys and runs. Naming a different document type is an error (A10) — the file has said it is not a scenario.
`name`	Scenario identity — must match the folder and filename.
`taxonomy`	Shared categorical dimensions, sampled on spawn (five strategies: `options`, `distribution`, `nested_distributions`, `dependency`, `weights`).
`catalog`	Named lookup tables of reference data.
`state_machines`	The entity types — fields, states, events, and references.
`messages` / `handlers`	Cross-entity messages and the handlers that react to them.
`scheduling`	The declared regime — `clock` (`tick`/`event`) and `partition` behaviour.

A minimal machine

type: mock_machines_scenario
name: Example

state_machines:
  - name: Order
    init_state: cart
    fields:
      - { name: total, type: measure }
    states:
      - name: cart
        events:
          - name: checkout
            probabilities: [0.7, 0.3]   # [stay, checkout]
            actions:
              - { type: transition, to: placed }
      - name: placed

Fields

YAML field categories — taxonomy, catalog, families, counters, dimensions, measures, and timestamp — flatten into one indexed []Field. Conditions and actions reference fields by integer index, not by name. A timestamp field stores a turn number, stamped in the hot loop by a declared trigger (on: create or on: enter, state: X) and exported only as a wall-clock column via a timing: block.

Actions

The update action carries an explicit operator (set / add / subtract); apply: all or a bracket expression (family[payload.x]) targets field-family members. Other actions: transition, new_entity, set_reference, emit_message.