Determinism and reproduction

PaymentChaos separates deterministic planning from nondeterministic application execution.

Seed and plan hash

A seed initializes PaymentChaos’s versioned pseudorandom generator. The compiled delivery order, delays, concurrency groups and chaos tags are deterministic, and they feed a stable plan hash. When a run reaches the report, it prints the seed on its first line and ends with a summary such as seed=1337 plan=dcc5…, showing a short hash prefix. plan prints the full hash:

node packages/cli/dist/bin.js plan paymentchaos/scenarios/renewal.yaml --seed 1337

Planning uses a logical clock and does not depend on local time, locale, Node’s random generator, or Math.random(). Write a negative seed as --seed=-5.

IDs and stable reproduction

By default, each repetition adds a fresh nonce to provider-shaped IDs, so repeated tests against a persistent database do not collide. Use --stable-ids when a reproduction must use exactly the same generated IDs:

node packages/cli/dist/bin.js run paymentchaos/scenarios/renewal.yaml \
  --seed 1337 --repeat 20 --repeat-index 4 --stable-ids

With --stable-ids, IDs depend only on the seed and match what plan prints. Every repetition then reuses the same IDs, so reset application state between repetitions, for example in a beforeEach hook. The flag cannot recover the nonce-based IDs of an earlier run made without it.

--repeat-index is one-based. Pass the same total --repeat value used in the original run.

The reproduce command

When an assertion fails, the report prints a reproduce: line. It reuses the Node binary and the PaymentChaos CLI copy that ran, so copying it never downloads a package:

reproduce: /usr/local/bin/node /work/paymentchaos/packages/cli/dist/bin.js run stripe-subscription-renewal --seed 1337

Run it from the same app directory. When the run had more than one repetition, it also adds --repeat and the failed --repeat-index. It keeps --stable-ids, --timeout-ms and --allow-remote-target if you used them. Secrets are never part of the command; they still come from your environment. On Windows, the printed command uses Command Prompt (cmd.exe) syntax. From PowerShell, enter cmd.exe, paste the command, then enter exit to return to PowerShell. Stay in the same app directory and keep the signing-secret environment variable set. If a Windows path contains ", % or !, the report asks you to rerun the same scenario and seed yourself, because cmd.exe cannot quote those safely.

The concurrency boundary

Dispatch order is deterministic, but a target server decides how concurrent requests interleave. Repeats improve the chance of exposing a race; they cannot prove that a race is absent. The report states how many repetitions failed and includes this limitation when concurrent deliveries pass.