Add composable qubit stochastic channels

[qciaran]

Summary

• add QubitStochasticChannel, a reusable single-qubit stochastic channel over PECOS's effective {|0>, |1>, |L>} space
• support four ordered channel stacks: before/after p1 sites and before/after p2 sites
• allow multiple independently sampled channels at each hook, with state changes visible to later channels
• apply p2 channels independently to each gate leg while retaining the existing correlated p2 Pauli/emission model
• support X, Y, Z, reset-like 0->1 / 1->0, wildcard leakage *->L (with L as an alias), state-selective leakage 0->L / 1->L, and recovery L->0 / L->1
• provide QubitStochasticChannel::leak_recovery(p, p_zero) for models such as 90% recovery per leaked qubit at every two-qubit gate
• reserve * for state wildcards by replacing QEC p2_weights replacement labels with compact ~XX and explicit :replace:XX spellings

Channel probability model

Each channel has an overall component-selection probability p and a map of non-negative relative event weights. The weights are normalized internally and do not need to sum to one. If the event coin fails, the effective-qutrit identity is implicit; users do not need to include a near-one identity weight.

For event weight w_i, component i is selected with probability p * w_i / sum(w). A selected component can preserve some inputs: for example, L->0 preserves computational inputs, while 0->1 is a reset-like map to |1> and therefore already preserves |1>. Consequently, p is the chance of selecting a component map, not necessarily the chance that every input changes.

These are fixed stochastic mixtures of named CPTP component maps, not an arbitrary Kraus-operator interface. PECOS tracks computational-versus-leaked occupation classically and does not preserve coherence between those sectors. State-selective 0->L and 1->L components use an internal Z measurement and leak only the matching population; the internal result is consumed by the noise model and never returned as a program measurement.

The existing p1/p2 Pauli and emission models remain unchanged and are still the preferred APIs for ordinary gate-local Pauli noise. Stochastic channels are intended for leakage/recovery composition or explicit before/after placement. Channel application probabilities follow the existing global and p1/p2 scale factors; *->L also follows the existing leakage_scale behavior.

Ordering

Before-gate stacks run before leakage suppression and ordinary gate noise, so recovery can allow an incoming leaked qubit to participate in the ideal gate and leakage can suppress it. After-gate stacks run after ideal-gate processing and ordinary Pauli/emission noise, so they can recover either incoming leakage or leakage generated at the same gate. All channels at a hook execute in insertion order and recompute leakage state between components. The p2 after-gate stack runs before configured after-2Q idle noise.

Existing GeneralNoiseModel behavior is unchanged when no stochastic channels are configured. Correlated pair components such as xy->wz remain a future extension.

QEC replacement-label syntax

Plain p2_weights labels such as XX remain post-gate Pauli branches. Replacement branches now use either ~XX or the equivalent :replace:XX; ~II / :replace:II means omit the ideal gate without applying a Pauli. Providing both aliases for the same normalized branch is rejected. The former *XX spelling is deliberately rejected with a migration hint so that * has one consistent meaning: an input-state wildcard such as *->L.

Validation

• cargo fmt --all -- --check
• cargo test -p pecos-engines --lib: 193 passed
• cargo test -p pecos-qec --lib: 637 passed
• cargo check -p pecos-rslib --tests
• cargo clippy -p pecos-engines -p pecos-qec -p pecos-rslib --all-targets -- -D warnings
• cargo test -p pecos-engines --doc: 24 passed, including compile-fail examples
• git diff --check

The focused pecos-rslib unit-test executable cannot link on this machine because its configured Xcode Python 3.9 library path is absent; the binding and its new parser tests do pass the test-target type check.

Follow-up

The Selene PECOS wrapper does not yet expose GeneralNoiseModel stochastic-channel stacks. That wrapper integration can follow once this core API is agreed.