Troubleshooting

A scenario I expect to pass is failing

Run it alone with the failure detail.
```
cargo build -p cli
target/debug/crucible-scenarios run CT-XXX-001
target/debug/crucible-scenarios run CT-XXX-001 --json
```
Expected-failure packs (negative, adversarial) should fail — check the declared outcome matches the observed classification. A FAIL status means the system did not behave as the scenario requires.
Check the invariant counts. Runs attach the full registry; a scenario that passes its assertions but violates conservation/ownership/ binding will fail at the invariants stage. expect-X-holds assertions failing with “not registered” mean the invariant key was misspelled or not attached.
Re-run in parallel. run --parallel and report --parallel must produce byte-identical outcomes to serial. A difference is a genuine determinism bug (shared state, registry mismatch) — file it.
Confirm the fixture posture. Transfers need both parties registered and unfrozen; withdrawals need a confidential balance. The fixtures doc lists what exists.

A declarative document is rejected

crucible-scenarios validate and cargo test -p scenario-format report the exact gate: malformed JSON → wrong format → wrong schema_version → semantic violation (duplicate ids, dangling references, confidential public inputs, zero timeout). Generate a canonical document from a real scenario to see the correct shape, or copy from examples/declarative/.

A fuzz target reports findings

Every finding records its seed and iteration and shrinks to a minimal case. Reproduce deterministically with the recorded seed:

target/debug/crucible-scenarios fuzz --seed <seed> --iterations 1000

Then convert the finding into a permanent CT-REG-* regression scenario (fuzz crate’s to_regression_case) and file it — regression scenarios are never deleted.

Parallelism concerns

run --parallel splits by category and keeps concurrency scenarios serial. If a report differs between serial and parallel modes, that is a defect in the harness or executor (outcomes are re-sorted into registry order), not an acceptable flake — file it under the reproducibility checklist.

Adapter / boundary questions

This repository never implements token accounting or proving logic. If you find yourself tempted to add balance math or proof construction inside a pack, the fix belongs in the simulator/prover adapters or the upstream repositories instead — the PR template enforces this boundary.