Simulations

A simulation runs one workload many times across different scenarios. You choose the workload, optional fault models, depth, timeout, and memory. Workers IO creates the individual runs and gives you logs, captured inputs, artifacts, and captured files.

Use simulations when you want confidence that one important behavior keeps working beyond the happy path.

What you need

Before you run a simulation, make sure you have:

• A connected project.
• A prepared project image.
• A workload command.
• A workload file path.
• Optional fault models.
• Optional external mocks.

Check your project:

wio projects ls
wio projects get <project-id>

If it is not prepared, request a prepare and wait for it to finish:

wio projects prepare <project-id>

Baseline first

Baseline means no fault model. Run this first so you know the workload works before adding operating stress.

wio simulate create <project-id> \
  --command "python3 .workers/workloads/checkout.py" \
  --workload-path ".workers/workloads/checkout.py" \
  --depth 1

If the baseline fails, fix the workload or application before adding faults. A faulted run is only useful when you trust the baseline.

Add faults and depth

After the baseline passes, add one fault model and more depth:

wio simulate create <project-id> \
  --command "python3 .workers/workloads/checkout.py" \
  --workload-path ".workers/workloads/checkout.py" \
  --faults slow-network \
  --depth 20 \
  --timeout 300 \
  --mem 1024

--depth is the number of runs per fault model:

• No --faults, --depth 1: one baseline run.
• One fault, --depth 20: 20 runs.
• Two faults, --depth 20: 40 runs.

Start small. Increase depth after the workload is stable and failures are useful.

Watch progress

List simulation batches:

wio simulate ls

Check one simulation:

wio simulate status <exploration-id>

List runs from one simulation:

wio workloads ls --simulation <exploration-id>

Find failures:

wio workloads ls --state failed

Run states

Runs move through these states:

• pending
• booting
• executing
• succeeded
• failed
• timedOut
• interrupted

Failed and timed-out runs are the ones to inspect first.

Inspect a failure

Start with details:

wio workloads get <run-id>

Then read logs:

wio workloads logs <run-id>

List artifacts:

wio artifacts ls <run-id>

Download one:

wio artifacts download <run-id> stdout.log

Use artifacts for data you need after a failure: logs, reports, snapshots, traces, or compact state dumps. Keep them focused so failure review stays fast.

Rerun and verify

Rerun a completed run with the same details:

wio workloads rerun <run-id>

Rerun creates a fresh run with the same command, seed, fault model, memory, timeout, branch, workload file, and mock configuration. This is the determinism check: with the same pinned inputs, the same seed should produce the same result. Record/replay is a separate debugging mechanism for a specific recorded execution; replay alone is not a substitute for same-seed reruns.

If your workload creates its own random generator, seed it from the run seed exposed in WENV_SEED or FORMAL_SEED. Avoid using wall time or a fresh root seed from runtime entropy APIs for workload setup, because that can make the workload vary even when the simulator seed is the same.

After the fix:

1. Sync the project.
2. Run the same workload and fault model again.
3. Confirm the invariant passes.
4. Increase depth after the focused case is stable.

That loop is the point of simulations: find a concrete failure, make it easy to understand, prove the fix, then search wider.

Good habits

• Run baseline first.
• Add one fault model at a time.
• Keep depth low while authoring a workload.
• Increase depth after the workload is stable.
• Use clear invariant output.
• Inspect the captured workload, fault, and mock files when debugging.
• Inspect the captured workload, fault, and mock files before changing too many things.
• Verify the fix with the same workload and fault model, then run broader coverage.