Consolidate DEM batch sampling onto SampleBatch with bulk accessors

[ciaranra]

Closes #448.

What changed

DemSampler exposed two near-identically named batch-sampling methods with swapped semantics: sample_batch returned raw Python lists while generate_samples returned the Rust-held SampleBatch. This PR consolidates them:

• Single entry point: sample_batch(num_shots, seed=None) -> SampleBatch on both DemSampler and ParsedDem. generate_samples is removed (all call sites migrated; zero references remain). sample_batch_with_pauli_masks also returns a SampleBatch now.
• Bulk accessors on SampleBatch: detector_events() and observable_flips() return shots-major list[list[bool]], correct past 64 observables. These replace the old raw-tuple return; a former det, obs = sampler.sample_batch(...) becomes a batch call followed by the two accessors.
• Explicit observable width: the SampleBatch constructor takes keyword-only num_observables; a mask bit at or above it is a ValueError. When omitted, width is inferred from the highest set bit (documented, including the all-zero-masks case).
• Raw-measurement batches fail loud: sample_batch on a raw-measurements-mode sampler returns a batch whose rows are measurements, not detector events. Data accessors work; every decode path — the six methods on SampleBatch and the five decoder objects that accept one (LogicalSubgraphDecoder.decode_count/decode_count_parallel, WindowedLogicalSubgraphDecoder.decode_count, LogicalAlgorithmDecoder.decode_count, LogicalCircuitDecoder.decode_count) — rejects such batches with a ValueError instead of silently decoding measurements as syndromes.
• Type stubs: pecos_rslib.pyi gains coverage for the pecos_rslib.qec submodule (previously absent entirely).
• Docs: a tested section in docs/user-guide/dem-from-guppy.md covering sampling into a batch, bulk extraction, and the decoder-comparison methods (decode_count, decode_each, decode_stats). Escaped-backtick artifacts removed from touched docstrings.

Breaking changes

• DemSampler.generate_samples / ParsedDem raw-tuple sample_batch are gone; old tuple-unpack call sites fail loudly with a TypeError.
• Seeded reproducibility: in detector-events mode sample_batch now uses the geometric columnar sampling path (previously generate_samples' path), so fixed-seed results differ from the prior release; the distribution is unchanged.

Tests

• Bulk accessors round-trip against per-shot accessors at 73 shots (partial final word) and at 70 observables against get_observable_mask_wide (no truncation).
• An independent-oracle test pins exact column positions (error(1.0) D0 D2 L0 must yield [True, False, True] rows), so a column-mapping bug cannot pass by symmetric misreading.
• Pauli-mask XOR is asserted through the new return type against PauliFrameLookup.compute_mask_xor.
• Raw-batch rejection is tested on both a SampleBatch method and a decoder-object path.
• Constructor width: explicit-width-with-empty-masks, inferred-width, and out-of-range-bit cases.

Verification

just build-debug clean; python/quantum-pecos/tests/qec/ 1147 passed, 1 skipped, 1 xfailed; python/quantum-pecos/tests/docs/ 247 passed with only the two pre-existing test_qec_guppy_block_9/10 failures (present on dev before this change, tracked separately); just lint clean with clippy cold on the changed crate.

Deferred follow-ups (numpy-shaped accessors, stub packaging/py.typed, the pre-existing doc-test failures) are recorded on #448. Note for #420: its docs examples use generate_samples; whichever merges second needs a small alignment pass.