Program RNG platform functions (incl. RNGadvance) need a canonical home in the pecos-neo path, not the retiring engines

[ciaranra]

Context

PR #330 adds RNGadvance(delta) (relative stream movement / rewind) to the Python RNGModel (python/quantum-pecos/src/pecos/engines/cvm/rng_model.py). The logic is correct and well-tested, but that RNGModel is reached only by the legacy hybrid_engine_old.py. We're treating #330 as a contained fix for that legacy workflow.

The broader picture: program-level RNG platform functions (RNGseed, RNGbound, RNGindex, RNGnum, RNGadvance) are fragmented and mostly absent from the newer workflows.

Workflow	Classical interpreter	RNG platform fns	RNGadvance
hybrid_engine_old.py (legacy)	Python cvm RNGModel	seed/bound/index/num	yes (#330)
hybrid_engine.py	RustPhirClassicalInterpreter (pecos-phir-json)	none	no
sim() — QASM	pecos-qasm engine	seed/bound/index/num	no
sim() — PHIR/HUGR/Guppy	pecos-phir-json / pecos-hugr	none	no
sim_neo()	pecos_rslib_exp / pecos-neo	none	no

(.seed() on sim()/sim_neo() is the Monte-Carlo noise sampling seed — a separate mechanism from program RNG.)

Strategic direction

Per the pecos-neo default transition (strangler-fig: route sim() to pecos-neo, then collapse the other workflows onto it; see #151 for the canonical Rust RNGModel), we should not scatter RNG implementations across pecos-qasm / pecos-phir-json / pecos-hugr — those classical paths are on the retirement track. Investing there is throwaway work.

Instead: program RNG (including RNGadvance) should land once, in the canonical Rust RNGModel (#151) consumed by the pecos-neo classical path, so it's there when the other workflows migrate.

Proposed work

1. Establish program RNG as a tracked item in the neo transition (sibling to the existing G-series gaps), with the Rust RNGModel as the single source of truth.
2. Port set_relative_index/RNGadvance (rejection-sampling-aware rewind via replay of the historical bound sequence) into the Rust RNGModel; wire the pecos-neo classical path to all RNG platform functions.
3. Resolve the cross-engine semantic that fix: add RNGadvance support to legacy Python CVM #330 introduced: Python set_seed now resets count and clears bound history; Rust set_seed (rng_pcg.rs:311) does not — pick one and make the canonical model match.
4. Add end-to-end tests (program → RNG functions incl. advance → assert draws) against the neo path.
5. Leave the retiring engines (pecos-qasm, pecos-phir-json, pecos-hugr) as-is for RNG; let migration carry them onto the neo implementation rather than back-porting.

Refs: #330, #151

[qartik]

Happy to avoid merging #330 if this is the direction taken and can be prioritized sooner.

[ciaranra]

Nah, it is fine. It will take a while to migrate everything to the new simulation workflow

[ciaranra]

This is more of a note to myself not to forget the RNG stuff and to make sure to transfer what is done to the new workflow and skip the intermediates.

[ciaranra]

Field data point for the canonical-RNG design (2026-08-07, from PR #453's CI and fixed in PR #454):

pecos-neo's test_multiple_shots failed its statistical 50/50 assertion ("got 70/30", ~8e-5 per-run odds at n=100) despite calling CircuitRunner::with_seed(42). The runner seed governs noise sampling only; measurement outcomes draw from the simulator's own RNG, and the test constructed SparseStab::new (entropy-seeded). The crate's lead doc example showed .with_seed(42) on a noiseless run — where it does nothing — which is what taught the misuse. PR #454 seeds the simulator in the test, corrects the example, and documents the contract on with_seed.

A sweep found this was the only test in the crate depending on hidden entropy (every other statistical test seeds an explicit PecosRng it passes in), but the incident is a concrete requirement for this issue's design: the canonical RNG platform should make whole-run determinism a single-knob operation — a program/runner seed that deterministically derives the simulator RNG, noise RNG, and any per-shot streams (the recorded per-shot seeding gap), so that a fixed seed can never again coexist with nondeterministic outcomes. Current counts of the entropy-seeded constructor pattern in exp/pecos-neo: 83 call sites under tests/, 153 under src/ — worth migrating (or making impossible) as part of landing the canonical model.