Doc tests for qec-guppy transversal-CNOT examples fail with a HUGR execution stall

[ciaranra]

Bug

Two generated doc tests for docs/user-guide/qec-guppy.md fail with a HUGR
execution stall:

RuntimeError: Simulation failed: HUGR execution stalled before completion; results
would be silently truncated (active CFGs: [Node(4), Node(302)]; active Calls:
[Node(81)]; starved deferred nodes: {Node(310)}; unexecuted ops in executed
containers (22 total): [... collections.borrow_arr.clone / borrow_arr.scan /
borrow_arr.to_array / tket.result.result_array_bool ...])

Affected tests: test_qec_guppy_block_9 and test_qec_guppy_block_10
(from docs/user-guide/qec-guppy.md around the transversal-CNOT examples).
Both blocks run sim(...) over make_css_transversal_cnot(...) with
state_vector().

Notes

• The stall detector is working as designed — it fails loud rather than
  silently truncating results — so the defect is upstream of it, in execution of
  the borrow-array / result_array_bool op sequence inside a CFG.
• Reproduced on the guppy-dem-idle-docs branch both before and after the
  doc-test generator change made there, so it is independent of that work; the
  failing blocks touch no API changed by PR Align idle-noise vocabulary across DEM, engines and neo, and emit the requested Pauli channel #420.
• Needs a dev baseline run to confirm how long it has been failing and whether
  it is a regression against the borrow-array work that closed earlier.

Reproduce

uv run --frozen python scripts/docs/generate_doc_tests.py
uv run pytest python/quantum-pecos/tests/docs/generated/user_guide/test_qec_guppy.py -q

[ciaranra]

Investigation status: reproduced and narrowed, not yet isolated

Reproduction

from pecos import sim, state_vector
from pecos.guppy import get_transversal_num_qubits, make_css_transversal_cnot

prog = make_css_transversal_cnot(code_type="color", distance=3, num_rounds=1)
n = get_transversal_num_qubits("color", 3)
sim(prog).qubits(n).quantum(state_vector()).seed(42).run(2)

Reliable, and not specific to the round loop:

• fails for code_type="color" and "surface"
• fails with num_rounds=0 as well as 1

Unrelated to the branch it was found on: it reproduces with none of that branch's
changes applied, and the failing blocks touch no API those changes affect.

Constructs ruled out (each verified by execution; all run fine)

Working up from minimal programs, on the same sim(...).quantum(state_vector()) path:

1. array-valued result() on a literal array
2. array result inside a range(comptime(n)) loop
3. an array passed to a called function, then array result
4. loop + call + array result combined
5. a @guppy.struct with an array field consumed @owned, measured via
   measure_array(struct.field), returned as array[bool, N] from a called function
6. an array built by comprehension: array(qubit() for _ in range(2))
7. array result on a struct field (the syn.synx shape) inside a runtime loop,
   where the struct is returned from a called function
8. result() on a literal bool returned from a call (0 qubits)
9. result() on an inline bool
10. result() on a measurement returned from an @owned call
11. two such calls in sequence

Two confident hypotheses were wrong along the way: the owned-struct measurement (5),
and the array comprehension (6) — the latter looked compelling because it is what
emits the borrow_arr.scan/to_array ops named in the stall message.

Where to go next

Building minimal cases upward stopped converging. The efficient route is bisecting
downward from the real generated program, which is 257 lines and obtainable
directly:

from pecos.guppy.transversal import generate_color_transversal_source
src = generate_color_transversal_source(3)

pecos/guppy/transversal.py::_load_css_transversal_module shows how it is loaded and
how the make_transversal_cnot(num_rounds) factory is called.

An automated bisection was attempted and got as far as building a harness whose case
names suggest it was narrowing on call-versus-inline reset/measure with result();
the run was terminated by a provider-side content filter (a false positive on this
benign QEC work) before it reported. Cases 8-11 above were the manual follow-up of
that scent and all pass, so that line is probably not it either.

Also worth doing: find where the HUGR execution stalled message is emitted under
crates/ and read the readiness/deferred-node logic, to determine why the reported
node is starved. The stall detector itself appears to be behaving correctly — failing
loud rather than silently truncating results — so the defect is upstream of it, and
the open question is whether it lives in the executor, in the generated program, or in
guppylang's emitted HUGR.

[ciaranra]

Resolved the open question in the Notes: this is pre-existing on dev, not a regression from #420.

Established without needing a baseline build:

• The stalling ops (collections.borrow_arr.*, tket.result.result_array_bool) are owned by crates/pecos-hugr — src/loader.rs, src/engine/handlers/result.rs, src/engine/handlers.rs, src/result_tags.rs.
• Branch guppy-dem-idle-docs (PR Align idle-noise vocabulary across DEM, engines and neo, and emit the requested Pauli channel #420) does not touch crates/pecos-hugr at all. Its changed crates are pecos, pecos-cli, pecos-engines, pecos-qasm, pecos-qec, benchmarks, exp/pecos-neo, python/pecos-rslib, python/quantum-pecos.
• docs/user-guide/qec-guppy.md is byte-identical to dev (git diff dev...HEAD -- docs/user-guide/qec-guppy.md is empty), so the failing blocks are unchanged.

So the defect predates the branch and lives in the HUGR execution path, as the original notes suspected. The dev baseline run is no longer needed to answer whether it is a regression; it would only date the introduction.

Still not isolated. A previous bisection attempt on this branch was killed mid-run by a provider content filter, and no narrower reproducer has been found beyond what is already recorded: it reproduces for both color and surface codes, and at num_rounds=0.