Select and Audit Logical Artifacts¶

Bridge returns an immutable canonical logical artifact and may return an exact optimized child. This guide shows how to use the recommendation without losing the canonical audit trail.

Select the Recommended Inline Artifact¶

from qdsv_bridge import QDSVBridgeClient, select_recommended_artifact

result = QDSVBridgeClient().generate(spec)
canonical = result["artifact"]
recommended = select_recommended_artifact(result)

print(canonical["role"])
print(result["recommended_artifact_role"])
print(recommended["content"])

select_recommended_artifact returns the optimized child only when Bridge declares it recommended and its content is available inline. Otherwise it returns the canonical artifact. Metadata-only delivery raises QDSVBridgeAPIError instead of pretending that circuit content is present.

Inspect Optimization Evidence¶

optimization = result["logical_optimization"]

print(optimization["status"])
print(optimization["profile"])
print(optimization["acceptance_policy"])
print(optimization["resources_before"])
print(optimization["resources_after"])
print(result["digests"])

The exact response may include additional evidence fields as the public contract evolves. Treat the status, profile, acceptance policy, resources, digests and artifact roles as evidence; do not infer hardware quality from them.

Freeze the Public Profile¶

The bounded-predicate helper can freeze the versioned public contract for a reproducible run:

from qdsv_bridge import build_predicate_spec

spec = build_predicate_spec(
    rows=rows,
    predicate=predicate,
    logical_optimization={
        "mode": "auto",
        "profile": "qiskit_structural_exact_v1",
        "acceptance_policy": "pareto_no_regression_v1",
    },
)

For a manually assembled specification, place the same mapping in target.logical_optimization. Custom passes, physical targets, layouts, routing and approximation settings are outside the public Bridge contract.

Request Canonical-only Delivery¶

Set target.logical_optimization to false when a workflow requires the byte-for-byte canonical artifact and no optimized child should be attempted. This does not disable semantic construction verification.

Hand Off to a Physical Workflow¶

Choose the logical artifact first, preserve its role and digests, and then pass it to Runtime/HSP or an equivalent user-controlled target-aware workflow:

canonical or accepted optimized logical artifact
-> backend selection and calibration snapshot
-> target-aware transpilation, layout and routing
-> exact replay of the frozen physical artifact
-> authorized provider execution
-> separate hardware evidence

Bridge does not perform the physical stages in this sequence.