Document layered QEC abstractions and end-to-end workflows

[qciaran]

Summary

Update PECOS architecture documentation and examples to describe the agreed layered QEC model, lowering boundaries, experiment/noise attachment points, and end-to-end workflows.

Parent: #509
Architectural discussion: #508

Motivation

crates/pecos-qec/docs/levels-of-abstraction.md already distinguishes abstract codes, geometry, circuits, and programs. The RFC expands this into a coherent refinement pipeline reaching target-native timed execution and clarifies that code-capacity, phenomenological, and circuit-level models are experiment overlays rather than different code types.

Documentation should guide both users choosing the right abstraction and contributors deciding where new functionality belongs.

Scope

• Revise the abstraction-level document after the RFC reaches an initial decision.
• Document responsibilities, inputs, outputs, and invariants for each persistent representation.
• Explain lowering and source/provenance maps.
• Explain where geometry, decoders, Pauli frames, detector models, noise, and calibration data belong.
• Distinguish logical programs from executable device programs to avoid overloading "program."
• Add diagrams and API examples only where they materially clarify the relationships.
• Document qecdb as an abstract-code catalog input.
• Include the HDL-inspired frontend model if that exploration is accepted.

End-to-end examples

At minimum, document:

1. Local stabilizers -> validated abstract code -> code-capacity analysis.
2. Abstract code -> syndrome-extraction plan -> synthesized/verified circuit -> circuit-level simulation.
3. QEC implementation -> target mapping -> native timed schedule with provenance.
4. qecdb record -> abstract code -> independently selected PECOS protocol.

Acceptance criteria

• Documentation matches implemented public APIs and passes existing docs-example tests.
• Each abstraction has a concise "use this when" description.
• Noise/experiment models have explicit attachment points.
• At least one complete executable example retains traceability from abstract checks/logicals to emitted measurements and results.
• Outdated examples using superseded type names or boundaries are migrated.

[qciaran]

Design update: space-time and hierarchy visualization

Documentation and examples should include visualization requirements for the proposed hierarchical space-time representation. The visualization should be derived from the same semantic/layout model used for analysis rather than maintained as a separate visual-only scene graph.

Candidate coordinated views:

• conventional qubit-lane versus time circuit view;
• Gantt-style nested gadget/protocol timing view;
• physical-device geometry animated or sliced through time;
• 3D space-time volume view for patches, surgery, routing, and logical operations;
• hierarchy drill-down from logical operation to gadget, round, and physical gates;
• semantic overlays for stabilizers, detectors, logical observables, error propagation, resource conflicts, and critical paths.

At least one documented example should show the same Steane or surface-code operation at multiple abstraction levels and demonstrate selecting a volume to trace it back to its semantic contract and down to its flattened operations.