sim

Overview ¶

Command sim runs the GoGraph deterministic simulation testing (DST) harness.

Usage:

go run ./cmd/sim [seed] [flags]

With no seed argument a random seed is chosen (from a non-deterministic source used solely to pick the seed value) and printed so the run can be reproduced. Flags:

--ticks       number of ticks (operations) to simulate (default 100000)
--check-every invariant-check cadence in ticks (default 1 = every tick);
              >1 trades check coverage for speed on long runs. The terminal
              tick is always checked regardless, so a violation in the final
              ticks is never missed.
--workload    actor mix: default | write-heavy | read-heavy | bad-actor
--verbose     print each operation as it runs
--crashes     inject deterministic crash+recovery cycles
--checkpoint  enable in-loop checkpointing (full-stack WAL + snapshot store);
              periodically publishes a real snapshot and truncates the WAL
              prefix, so a crash recovers via the full snapshot+WAL path
--checkpoint-every  tick cadence between checkpoints (0 = default cadence)
--mode        engine | wire | concurrent | liveness (default "engine")
--conns       concurrent connections for the concurrent/liveness modes
--ops-per-conn  operations per connection for those modes
--scenario      run a named scenario from the catalogue (see --list-scenarios)
--list-scenarios  print the scenario catalogue and exit
--replay        re-run the seed in verbose full-trace debug; on a violation,
                shrink to a minimal reproducer and print it
--swarm         run a swarm of many derived seeds across a bounded worker
                pool, time/count-boxed; prints a summary (runs/passes/
                failures with reproduce lines) and exits non-zero on any
                failing seed. Tuned by --workers, --runs, --duration, and an
                optional --scenario filter; --bias steers selection toward
                under-covered scenarios; --coverage-report prints coverage.
                The leading positional seed is the swarm's MASTER seed, so
                the whole swarm reproduces from it.

Scenario and replay modes (Phase 4):

--list-scenarios            prints the catalogue (name, mode, default seed)
--scenario=<name> [seed]    runs a named scenario; exit 1 on a violation
--replay=<seed> [--scenario=<name>]
                            re-runs a DETERMINISTIC workload for the seed,
                            printing every op; on a violation it shrinks the
                            recorded trace to a minimal reproducer (ddmin) and
                            prints it with the reproduce line, exiting 1

The Phase-3 modes drive the REAL Bolt wire protocol against a genuine bolt/server over an in-memory connection:

wire        a deterministic LOCK-STEP single-connection round-trip demo
concurrent  N real goroutines, one per connection (NOT bit-reproducible);
            asserts eventual oracle==engine consistency, no panic, no leak
liveness    a two-phase safety->liveness run with convergence + a
            deadlock/resonance watchdog

On a violation the report (which includes a "Reproduce with:" line) is printed to stderr and the process exits 1. On success a one-line summary is printed and the process exits 0.