Glossary
The terms used throughout the docs and the codebase.
| Term | Meaning |
|---|---|
| Scenario | A self-identifying config package under scenarios/<Name>/ — the folder, the name: field, and the filename all agree. The authoring source on disk. |
| State machine | An entity type: a set of states, the events that move between them, and the typed fields each instance carries. |
| Entity | One instance of a state machine — a current state plus its fields and references. Stored as an EntityHandle{machineIdx, row} coordinate. |
| State | A node in a machine’s lifecycle. Each state owns a probability matrix with one row per Age and columns [stay, event_0, …]. |
| Age | Turns since the entity entered its current state; indexes the probability matrix. Resets to 0 on every transition. |
| Event | A possible transition trigger, selected from the state’s probability row, gated by conditions, producing actions. |
| Action | An effect of an event: transition, update, new_entity, set_reference, or emit_message. |
| Condition | A predicate over field values that gates whether an event may fire. |
| Taxonomy | A shared catalog of categorical dimensions sampled on spawn via one of five strategies, forming a dependency DAG. |
| Archetype | The columnar struct-of-arrays storage for all live entities of one machine type — the basis for O(1), reflection-free field access. |
| Partition | A set of machines connected by spawn/message/reference edges, unioned at load. Disjoint partitions share no state and run independently. |
| Cascade | The within-turn queue of messages delivered to handlers before the next turn begins. |
| Clock | A partition’s time model: tick (fixed discrete steps) or event (event-sourced, jumps to the next scheduled time). |
| Experiment | A single run of a deployed scenario — is its on-disk dataset (CSV/Parquet + manifest + event log), rehydrated on demand. |
| Event log | The JSONL record of every mutation during a run. Reconcilable: replaying it reproduces the exported tables. |
| OSI semantic layer | An open-semantic-interchange.org-compatible model (entities, dimensions, measures) emitted with a dataset. |