Quick Start

A scenario is a self-identifying package under scenarios/: the folder name, the config’s name: field, and the filename all agree, so the config lives at scenarios/<Name>/<Name>.yaml with any seed CSVs alongside it.

Validate a config

Running the engine with just a config path loads and validates it, then exits — a fast sanity check:

go run main.go scenarios/PaymentProcessor/PaymentProcessor.yaml
go run main.go scenarios/ProgrammaticAds/ProgrammaticAds.yaml

Run an experiment

Add --run <turns> to actually simulate:

# 100 seed entities per root machine, 50 turns
go run main.go -run 50 -seedCount 100 scenarios/PaymentProcessor/PaymentProcessor.yaml

A run writes one CSV per machine type, an experiment.json manifest, and a JSONL event_log.jsonl into the experiment directory. The event log is reconcilable — replaying it reproduces the exported tables.

Run the test suite

The full pipeline that CI runs, in order:

go vet ./...                                   # static analysis
go build ./...                                 # compile
go test ./...                                  # unit tests (skips integration-tagged)
go test -race -count=3 ./...                   # race detector, repeated to surface flakes
go test -tags=integration ./internal/engine/enginetest/   # scenario integration suite
go run main.go -run 50 scenarios/PaymentProcessor/PaymentProcessor.yaml   # e2e smoke test

Tip

To run every test — default plus integration-tagged — in one command: go test -tags=integration ./...

Next: the Config YAML reference for how a scenario is defined, or the CLI reference for every flag.