Integration with the Crucible polyrepos

crucible-simulator is one of three repositories:

The boundaries are interfaces, not imports. This repository defines what it needs and never reaches into the others.

With crucible-prover — the ProofProvider boundary

             crucible-prover
                    |
                    | implements ProofProvider
                    v
             crucible-simulator
                    |
                    v
              Flow engine -> State engine

• The interface lives here: ProofProvider (in crates/flows).
• crucible-prover implements it — mock, Noir, or UltraHonk, the simulator does not care.
• Today the simulator ships MockProofProvider, a deterministic stand-in so flows can run end to end. Validation still requires a proof reference for confidential transfers, so swapping in a real provider cannot silently weaken the pipeline.

A scenario says “generate proof”, the simulator says “prove this” through the provider, and the flow proceeds only on a valid reference.

With crucible-scenarios — the stable API

crucible-simulator          crucible-scenarios
        |                          |
        |  stable API (crates)     | scenario logic
        +------------------------->+

crucible-scenarios consumes the simulator through the stable public API and the published fixture corpus — it does not import internal modules. A scenario is expressed exactly the way the spec describes:

Create environment
Register Alice, Register Bob
Deposit to Alice
Generate proof (via the provider boundary)
Transfer Alice -> Bob
Assert result, assert state, assert events

Three things make that possible:

1. Deterministic outcomes — a scenario is fixture + environment + seed + operation sequence and its result is reproducible, so failures are communicated as (fixture, environment, seed, sequence).
2. Explicit transitions — every operation records State0 -> Transition -> State1, so a scenario can assert on intermediate and final state.
3. The privacy boundary — scenarios assert on private state through the labeled inspection APIs and on observable behavior through events/transactions, matching the distinction real Confidential Token semantics require.

Compatibility guarantees

The simulator API carries explicit stability expectations because crucible-scenarios builds on it: semantic versioning, an audited transition log, and a deterministic state-root scheme whose changes are tracked (see docs/deterministic-execution.md).