Glossary
The terms used throughout the docs and the codebase.
Scenario
Section titled “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
Section titled “State machine”An entity type: a set of states, the events that move between them, and the typed fields each instance carries.
Entity
Section titled “Entity”One instance of a state machine — a current state plus its fields and references. Stored
as an EntityHandle{machineIdx, row} coordinate.
A node in a machine’s lifecycle. Each state owns a probability matrix with one row per Age
and columns [stay, event_0, …].
Turns since the entity entered its current state; indexes the probability matrix. Resets to 0 on every transition.
A possible transition trigger, selected from the state’s probability row, gated by conditions, producing actions.
Action
Section titled “Action”An effect of an event: transition, update, new_entity, set_reference, or
emit_message.
Condition
Section titled “Condition”A predicate over field values that gates whether an event may fire.
Reference
Section titled “Reference”A typed link from one entity to another. A machine declares reference slots, each naming
the entity type it points at; an instance’s slot resolves to a specific target, set on
spawn or by a set_reference action.
One typed value an entity carries — a counter, measure, dimension, taxonomy, catalog, family, or timestamp. Authoring groups fields by category, but they flatten into one indexed list, referenced by integer index in the hot loop.
Taxonomy
Section titled “Taxonomy”A shared catalog of categorical dimensions sampled on spawn via one of five strategies, forming a dependency DAG.
Message
Section titled “Message”A named signal one entity emits (emit_message) and another accepts; the engine delivers
it within the same turn’s cascade, where a matching handler reacts.
Archetype
Section titled “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
Section titled “Partition”A set of machines connected by spawn/message/reference edges, unioned at load. Disjoint partitions share no state and run independently.
Cascade
Section titled “Cascade”The within-turn queue of messages delivered to handlers before the next turn begins.
A partition’s time model: tick (fixed discrete steps) or event (event-sourced, jumps
to the next scheduled time).
Experiment
Section titled “Experiment”A single run of a deployed scenario — is its on-disk dataset (CSV/Parquet + manifest + event log), rehydrated on demand.
Event log
Section titled “Event log”The JSONL record of every mutation during a run. Reconcilable: replaying it reproduces the exported tables.
OSI semantic layer
Section titled “OSI semantic layer”An open-semantic-interchange.org-compatible model (entities, dimensions, measures) emitted with a dataset.