quantbom 0.6.0__py3-none-any.whl

quantbom/__init__.py

@@ -0,0 +1,497 @@
+"""QuantBOM SDK — certify a quantum release from your running Qrisp/Qiskit code.
+
+One env var + one line. Evidence is collected locally (your source never leaves
+the machine); only the QBOM/evidence bundle is sent to the QuantBOM service, which
+returns a signed CRA certificate that is also mirrored to ./.quantbom/<release>/.
+
+    export QUANTBOM_API_KEY=qb_live_...
+    import quantbom
+    result = quantbom.certify(my_circuit, release="portfolio-opt@1.2.3")
+    print(result["overall_status"], result["certificate"]["certificate_id"])
+
+Integration modes:
+  - post-run call:   quantbom.certify(circuit, release=...)
+  - decorator:       @quantbom.certified(release="...")  (the function returns a circuit)
+  - CLI:             quantbom certify --qpy circuit.qpy --release ...   (see quantbom.cli)
+  - two-step:        quantbom.collect(...) -> add partner evidence -> quantbom.certify(bundle=...)
+
+Fail-soft by default: if the service is unreachable or credits are exhausted, a
+warning is logged and your quantum workflow continues. Pass mode="gate" to raise
+/ exit non-zero on a non-compliant or failed result (for CI).
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Any, Callable
+
+# QuantBOM was called ZentroQ until 0.6.0: ZENTROQ_* settings keep working
+for _name, _value in list(os.environ.items()):
+    if _name.startswith("ZENTROQ_"):
+        os.environ.setdefault("QUANTBOM_" + _name[len("ZENTROQ_"):], _value)
+
+__all__ = ["certify", "certified", "collect", "configure", "keygen", "pin_keys", "sign", "verify", "wrap"]
+
+DEFAULT_API_URL = os.environ.get("QUANTBOM_API_URL", "http://127.0.0.1:8088")
+MIRROR_FILES = ("csnap.json", "certificate.json", "certificate.json.att.json", "signing.pub", "verification.json")
+
+_config: dict[str, Any] = {"api_url": DEFAULT_API_URL, "api_key": os.environ.get("QUANTBOM_API_KEY"), "mirror_dir": ".quantbom"}
+
+
+def configure(api_url: str | None = None, api_key: str | None = None, mirror_dir: str | None = None) -> None:
+    if api_url:
+        _config["api_url"] = api_url
+    if api_key:
+        _config["api_key"] = api_key
+    if mirror_dir:
+        _config["mirror_dir"] = mirror_dir
+
+
+def _warn(msg: str) -> None:
+    print(f"[quantbom] {msg}", file=sys.stderr)
+
+
+def _detect_circuit(circuit: Any) -> tuple[Any, str, Any, str]:
+    """Return (qiskit_circuit, frontend_label, native_object_or_None, source_format).
+
+    Every supported frontend lowers to the normalized IR (qiskit.QuantumCircuit)
+    through its adapter in `frameworks/`; conversion libraries are lazy-imported
+    — if you built the object, you have its framework installed.
+    """
+    try:
+        import qiskit  # noqa: F401
+    except Exception as exc:  # pragma: no cover
+        raise RuntimeError("qiskit is required to collect evidence (pip install qiskit)") from exc
+    from .frameworks import detect
+
+    adapter = detect(circuit)
+    from ._circuit import refuse_dynamic, refuse_open
+
+    refuse_open(adapter.open_parameters(circuit), how="resolve them in your framework, or give each QNode argument a value")
+    if not adapter.supports_dynamic:  # before lowering: one message, not the exporter's
+        refuse_dynamic(adapter.dynamic_features(circuit), adapter.name)
+    qiskit_circuit, label, native = adapter.lower(circuit)
+    return qiskit_circuit, label, native, adapter.name
+
+
+def _collect_evidence(release: str, evidence_dir: Path, *, circuit=None, qpy=None, qasm3=None, backend: str = "basic", equivalence: bool = False, expected=None, tolerance: float = 0.05, expected_order: str = "native") -> Path:
+    """Build the local evidence bundle (the mirror) using the bundled collector."""
+    from . import _collect as qe
+    from ._bitorder import to_measured_order
+
+    fidelity = None
+    native_export = None
+    native_result = None
+    if circuit is not None:
+        qk, label, qrisp_circ, fmt = _detect_circuit(circuit)
+        # QNT-06: only here is the native Cirq/Braket/PennyLane object still in
+        # hand, so the conversion is checked before it is discarded — and its
+        # export kept, to be written hash-bound beside the report.
+        from ._fidelity import assess_conversion, sample_native
+        from .frameworks import get as _get
+
+        fidelity = assess_conversion(circuit, qk, fmt)
+        # QNT-09: the same native object, sampled on its own framework's simulator
+        native_result = sample_native(circuit, qk, fmt)
+        if fidelity is not None:
+            try:
+                native_export = _get(fmt).native_export(circuit)
+            except Exception:  # the report already says what the export could not do
+                native_export = None
+    elif qpy is not None:
+        qk, label, qrisp_circ, fmt = qe.load_circuit("qpy", str(qpy))
+    elif qasm3 is not None:
+        qk, label, qrisp_circ, fmt = qe.load_circuit("qasm3", str(qasm3))
+    else:
+        raise ValueError("provide one of: circuit=, qpy=, qasm3=")
+
+    # Expected results are written in the framework's own bit order; results
+    # are measured in Qiskit's. Translate (and validate) before anything is
+    # written, so a malformed declaration fails here rather than as `exceeded`.
+    declaration = None
+    if expected:
+        from .frameworks import get as _adapter
+
+        adapter = _adapter(fmt) if circuit is not None else None  # file inputs are Qiskit's own
+        expected, declaration = to_measured_order(
+            expected, fmt, qk, expected_order,
+            native_order=adapter.bit_order_for(circuit) if adapter else None,
+            measured_order=adapter.measured_order_for(circuit) if adapter else "qubit0_last",
+        )
+
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    qe.collect(release_id=release, out_dir=evidence_dir, qiskit_circuit=qk,
+               frontend_label=label, qrisp_circuit=qrisp_circ, source_format=fmt, backend_choice=backend,
+               equivalence_check=equivalence, expected_distribution=expected, expected_tolerance=tolerance,
+               expected_declaration=declaration, conversion_fidelity=fidelity, native_export=native_export,
+               native_result=native_result)
+    return evidence_dir / "sbom.cdx.json"
+
+
+def collect(circuit=None, release: str = "release", out_dir=None, *, qpy=None, qasm3=None, backend: str = "basic",
+            equivalence: bool = False, expected=None, tolerance: float = 0.05, expected_order: str = "native",
+            environment: bool = False, syft_sbom=None, vuln_scan: bool = False, grype_output=None) -> Path:
+    """Collect the evidence bundle locally, without contacting the service.
+
+    The first half of `certify()`, for when evidence from elsewhere must join
+    the bundle before it is certified: partner modules' attestations (MOD-05
+    tests, MOD-07 vulnerability handling, MOD-03/09 crypto) and the release
+    signature are added to the directory by their own tools — see
+    `quantbom actions` for each one's command — and the result is certified
+    with `certify(bundle=out_dir)`. Returns the path of the QBOM.
+    """
+    out = Path(out_dir) if out_dir is not None else Path(_config["mirror_dir"]) / _safe(release)
+    sbom_path = _collect_evidence(release, out, circuit=circuit, qpy=qpy, qasm3=qasm3, backend=backend,
+                                  equivalence=equivalence, expected=expected, tolerance=tolerance,
+                                  expected_order=expected_order)
+    _merge_environment_sbom(sbom_path, syft_sbom=syft_sbom, environment=environment)
+    _scan_vulnerabilities(sbom_path, vuln_scan=vuln_scan, grype_output=grype_output)
+    return sbom_path
+
+
+def _zip_dir(evidence_dir: Path, exclude: tuple[str, ...] = ()) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for path in sorted(evidence_dir.rglob("*")):
+            rel = str(path.relative_to(evidence_dir))
+            # mirror files live at the bundle ROOT; matching by basename once dropped
+            # the producer's evidence/signing.pub, so a producer signature could not
+            # verify on the service (masked while the service re-signed everything)
+            if path.is_file() and rel not in MIRROR_FILES and rel not in exclude:
+                zf.write(path, arcname=rel)
+    return buf.getvalue()
+
+
+# privacy="strict": these circuit-IR files never leave the machine. The bytes
+# stay in the local mirror (the producer's audit bundle); only their digests
+# travel, marked client-attested on the certificate.
+STRICT_WITHHELD = (
+    ("quantum/circuit.qpy", "secqdevops:circuit-sha256"),
+    ("quantum/transpiled.qpy", "secqdevops:transpiled-circuit-sha256"),
+    ("quantum/program.qasm", "secqdevops:qasm-program-sha256"),
+)
+# ... and so a producer signature made for a strict upload must not cover them:
+# the service verifies every signed subject against the bytes it received.
+STRICT_WITHHELD_REFS = (
+    "secqdevops:circuit-artifact-ref",
+    "secqdevops:transpiled-circuit-ref",
+    "secqdevops:qasm-program-ref",
+)
+
+
+def _apply_strict_privacy(sbom_path: Path, evidence_dir: Path) -> tuple[str, ...]:
+    """Re-verify the withheld digests locally, then mark the SBOM strict.
+
+    Attesting requires verifying: each withheld file's bytes are re-hashed
+    against the SBOM's claimed digest BEFORE it is withheld. A mismatch is a
+    hard error — we never attest digests we could not reproduce.
+    """
+    import hashlib
+
+    sbom = json.loads(sbom_path.read_text(encoding="utf-8"))
+    props = {p.get("name"): p.get("value") for p in sbom.get("metadata", {}).get("properties", [])}
+    withheld: list[str] = []
+    for rel, sha_prop in STRICT_WITHHELD:
+        path = evidence_dir / rel
+        claimed = props.get(sha_prop)
+        if not path.exists() or not claimed:
+            continue
+        actual = "sha256:" + hashlib.sha256(path.read_bytes()).hexdigest()
+        if actual != claimed:
+            raise RuntimeError(f"privacy=strict: local re-hash of {rel} does not match the QBOM ({claimed[:20]}… != {actual[:20]}…)")
+        withheld.append(rel)
+    properties = sbom.setdefault("metadata", {}).setdefault("properties", [])
+    properties[:] = [p for p in properties if p.get("name") != "secqdevops:privacy-mode"]
+    properties.append({"name": "secqdevops:privacy-mode", "value": "strict"})
+    sbom_path.write_text(json.dumps(sbom, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    return tuple(withheld)
+
+
+def _post_certify(zip_bytes: bytes, release: str, retain: bool = False, assurance: str = "standard", scheme: str = "eu-cra") -> dict[str, Any]:
+    url = _config["api_url"].rstrip("/") + "/v1/certify"
+    key = _config["api_key"]
+    if not key:
+        raise RuntimeError("no API key: set QUANTBOM_API_KEY or call quantbom.configure(api_key=...)")
+    headers = {"X-API-Key": key, "X-Release-Id": release, "Content-Type": "application/zip"}
+    if retain:  # opt-in server-side retention of the QBOM document + results (never artifact bytes)
+        headers["X-Retain"] = "1"
+    if assurance != "standard":  # opt-in server-side re-execution (costs an extra credit)
+        headers["X-Assurance"] = assurance
+    if scheme != "eu-cra":  # certify under an alternative compliance scheme (see /v1/schemes)
+        headers["X-Scheme"] = scheme
+    req = urllib.request.Request(url, data=zip_bytes, method="POST", headers=headers)
+    with urllib.request.urlopen(req, timeout=60) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _write_mirror(evidence_dir: Path, bundle: dict[str, Any]) -> None:
+    for name, content in (bundle or {}).items():
+        if content is None:
+            continue
+        path = evidence_dir / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(content, str):
+            path.write_text(content, encoding="utf-8")
+        else:
+            path.write_text(json.dumps(content, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+
+def _merge_environment_sbom(sbom_path: Path, *, syft_sbom=None, environment: bool = False) -> None:
+    """Optionally merge a full environment SBOM (syft) into the collected QBOM.
+
+    environment=True scans the running Python environment with a locally
+    installed syft (skipped with a warning when syft is absent); syft_sbom=
+    merges a pre-generated CycloneDX file. Both run client-side, before upload.
+    """
+    from . import _merge
+
+    if syft_sbom:
+        env = json.loads(Path(syft_sbom).read_text(encoding="utf-8"))
+    elif environment:
+        if not _merge.syft_available():
+            _warn("environment SBOM skipped — syft not found on PATH (quantum evidence still collected)")
+            return
+        env = _merge.run_syft(f"dir:{sys.prefix}")  # the running Python environment
+    else:
+        return
+    sbom = json.loads(sbom_path.read_text(encoding="utf-8"))
+    stats = _merge.merge_environment(sbom, env)
+    sbom_path.write_text(json.dumps(sbom, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    _warn(f"environment SBOM merged: +{stats['added']} components "
+          f"({stats['licenses_enriched']} licenses enriched, {stats['missing_license']} still unlicensed)")
+
+
+def _scan_vulnerabilities(sbom_path: Path, *, vuln_scan: bool = False, grype_output=None) -> None:
+    """Optionally populate the QBOM's vulnerabilities[] from a grype scan.
+
+    vuln_scan=True runs a locally installed grype over the collected (and
+    optionally syft-merged) QBOM — skipped with a warning when grype is
+    absent; grype_output= applies a pre-generated grype CycloneDX file.
+    """
+    from . import _scan
+
+    if grype_output:
+        scan_doc = json.loads(Path(grype_output).read_text(encoding="utf-8"))
+    elif vuln_scan:
+        if not _scan.grype_available():
+            _warn("vulnerability scan skipped — grype not found on PATH (gate will see an unscanned SBOM)")
+            return
+        scan_doc = _scan.run_grype(sbom_path)
+    else:
+        return
+    sbom = json.loads(sbom_path.read_text(encoding="utf-8"))
+    stats = _scan.apply_findings(sbom, scan_doc)
+    sbom_path.write_text(json.dumps(sbom, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    _warn(f"vulnerability scan: {stats['findings']} findings {stats.get('by_severity') or ''}")
+
+
+def certify(circuit=None, release: str = "release", *, backend: str = "basic", qpy=None, qasm3=None,
+            mode: str = "report", api_key: str | None = None, api_url: str | None = None,
+            syft_sbom=None, environment: bool = False, privacy: str = "standard",
+            vuln_scan: bool = False, grype_output=None, retain: bool = False,
+            equivalence: bool = False, expected=None, tolerance: float = 0.05,
+            assurance: str = "standard", scheme: str = "eu-cra", expected_order: str = "native",
+            bundle=None, sign: bool = False, signing_key=None) -> dict[str, Any]:
+    """Collect evidence locally, certify via the QuantBOM service, mirror the result.
+
+    Returns a result dict. mode="report" (default) never raises on policy outcome;
+    mode="gate" raises RuntimeError on a non-compliant or failed/unreachable result.
+    environment=True merges a full syft scan of the running Python environment into
+    the QBOM; syft_sbom= merges a pre-generated CycloneDX environment SBOM.
+    vuln_scan=True runs grype over the QBOM so CRA-ESR-03 and the VEX carry real
+    findings; grype_output= applies a pre-generated grype CycloneDX file.
+    privacy="strict" keeps the circuit-IR bytes (QPY/OpenQASM) on this machine:
+    only their locally re-verified digests travel, and the certificate marks them
+    client-attested. The local mirror retains the full bundle for on-site audit.
+    retain=True opts into server-side retention of the QBOM document + result
+    JSONs (never artifact bytes) — list/download/delete via /v1/releases.
+    equivalence=True formally checks source-vs-transpiled semantic equivalence
+    (mqt.qcec — pip install "quantbom[verify]"); the verdict ships as
+    hash-verified evidence and the gate's QNT-05 judges it.
+    expected={"0101": 1.0} declares the distribution the circuit should produce
+    (with tolerance= as max total-variation distance); the measured deviation
+    ships as hash-verified evidence and the gate's QBOM-BENCH-02 judges it.
+    Outcomes are read in YOUR framework's bit order (expected_order="native"):
+    Cirq, Braket and PennyLane put qubit 0 first, Qiskit and Qrisp put it last,
+    and the SDK translates before comparing. Pass expected_order="qiskit" to
+    write outcomes in measured (Qiskit) order instead. Every outcome must span
+    the full measured register; a wrong width raises immediately.
+    assurance="re-executed" asks the SERVICE to independently re-run the circuit
+    and reproduce the claimed results (privacy=standard only; costs an extra
+    credit); in gate mode, not achieving the requested assurance raises.
+    bundle=DIR certifies a bundle made by collect(), after partner evidence or
+    a release signature has been added to it; nothing is re-collected.
+    sign=True signs the evidence as its producer before upload (your key from
+    `quantbom keygen`, signing_key= or $QUANTBOM_SIGNING_KEY; needs
+    "quantbom[signing]") — the authorship claim CRA-SIGN-01 rests on. Without
+    it the service only countersigns what it received, and the certificate
+    says the producer did not sign.
+    """
+    if assurance not in ("standard", "re-executed"):
+        raise ValueError("assurance must be 'standard' or 're-executed'")
+    if privacy not in ("standard", "strict"):
+        raise ValueError("privacy must be 'standard' or 'strict'")
+    if bundle is not None and (circuit is not None or qpy is not None or qasm3 is not None):
+        raise ValueError("bundle= certifies an already-collected bundle; do not also pass a circuit")
+    if bundle is not None and (equivalence or expected):
+        raise ValueError("equivalence= and expected= are collection options: pass them to collect(), not certify(bundle=)")
+    if api_key or api_url:
+        configure(api_url=api_url, api_key=api_key)
+    evidence_dir = Path(bundle) if bundle is not None else Path(_config["mirror_dir"]) / _safe(release)
+
+    try:
+        if bundle is not None:
+            sbom_path = evidence_dir / "sbom.cdx.json"
+            if not sbom_path.is_file():
+                raise FileNotFoundError(f"{evidence_dir} is not an evidence bundle (no sbom.cdx.json); create one with quantbom.collect()")
+        else:
+            sbom_path = _collect_evidence(release, evidence_dir, circuit=circuit, qpy=qpy, qasm3=qasm3, backend=backend, equivalence=equivalence, expected=expected, tolerance=tolerance, expected_order=expected_order)
+        if equivalence and "secqdevops:equivalence-ref" not in sbom_path.read_text(encoding="utf-8"):
+            _warn("equivalence check skipped — mqt.qcec not installed (pip install \"quantbom[verify]\")")
+        _merge_environment_sbom(sbom_path, syft_sbom=syft_sbom, environment=environment)
+        _scan_vulnerabilities(sbom_path, vuln_scan=vuln_scan, grype_output=grype_output)
+        if sign:  # last, so the signature covers everything added above
+            from . import _sign
+
+            info = _sign.sign(evidence_dir, signing_key, omit_refs=STRICT_WITHHELD_REFS if privacy == "strict" else ())
+            _warn(f"evidence signed as producer, key {info['key_id'][:19]}… over {info['subjects']} artifacts")
+        withheld: tuple[str, ...] = ()
+        if privacy == "strict":
+            withheld = _apply_strict_privacy(sbom_path, evidence_dir)
+            _warn(f"privacy=strict — retained on this machine: {', '.join(withheld) or '(none)'}")
+        result = _post_certify(_zip_dir(evidence_dir, exclude=withheld), release, retain=retain, assurance=assurance, scheme=scheme)
+    except urllib.error.HTTPError as exc:
+        detail = _read_err(exc)
+        result = {"ok": False, "error": detail.get("error", f"HTTP {exc.code}"), "http_status": exc.code, "release_id": release}
+        if exc.code == 402:
+            _warn("out of credits — purchase more at the QuantBOM dashboard.")
+    except (urllib.error.URLError, Exception) as exc:  # fail-soft: never break the user's quantum run
+        result = {"ok": False, "error": str(exc), "release_id": release}
+
+    if result.get("bundle"):
+        _write_mirror(evidence_dir, result.pop("bundle"))
+        result["mirror"] = str(evidence_dir)
+        result["ok"] = True
+
+    _summarize(result)
+
+    if mode == "gate":
+        if not result.get("ok"):
+            raise RuntimeError(f"QuantBOM: certification could not be completed: {result.get('error')}")
+        if result.get("overall_status") != "COMPLIANT":
+            raise RuntimeError(f"QuantBOM gate failed: release is {result.get('overall_status')}")
+        if assurance == "re-executed" and result.get("assurance") != "service-re-executed":
+            note = (result.get("reexecution") or {}).get("note") or (result.get("reexecution") or {}).get("verdict")
+            raise RuntimeError(f"QuantBOM: requested re-executed assurance not achieved ({result.get('assurance')}: {note})")
+    return result
+
+
+def _extract_circuits(pubs) -> list:
+    """Pull qiskit circuits out of a primitive's run() argument (PUBs or a bare circuit)."""
+    from qiskit import QuantumCircuit
+
+    if isinstance(pubs, QuantumCircuit):
+        return [pubs]
+    seq = pubs if isinstance(pubs, (list, tuple)) else [pubs]
+    out = []
+    for pub in seq:
+        if isinstance(pub, QuantumCircuit):
+            out.append(pub)
+        elif isinstance(pub, (list, tuple)) and pub and isinstance(pub[0], QuantumCircuit):
+            out.append(pub[0])
+    return out
+
+
+def wrap(primitive, release: str = "release", **kwargs):
+    """Wrap a Qiskit primitive (SamplerV2/EstimatorV2) so `.run(...)` certifies transparently.
+
+        from qiskit_ibm_runtime import SamplerV2
+        sampler = quantbom.wrap(SamplerV2(mode=backend), release="vqe@2.1")
+        job = sampler.run([circuit])   # certifies the circuit, then runs as normal
+
+    Certification is fire-and-forget and fail-soft — it never blocks or breaks the run.
+    """
+    original_run = primitive.run
+
+    def run(pubs, *a, **k):
+        try:
+            circuits = _extract_circuits(pubs)
+            for i, circ in enumerate(circuits):
+                rel = release if len(circuits) == 1 else release + "-" + str(i)
+                certify(circ, release=rel, **kwargs)
+        except Exception as exc:  # never let certification break the user's run
+            _warn("wrap: certification skipped — " + str(exc))
+        return original_run(pubs, *a, **k)
+
+    primitive.run = run
+    return primitive
+
+
+def certified(release: str = "release", **kwargs) -> Callable:
+    """Decorator: certify the qiskit/qrisp circuit returned by the wrapped function."""
+    def deco(fn: Callable) -> Callable:
+        def wrapper(*a, **k):
+            out = fn(*a, **k)
+            circuit = out[0] if isinstance(out, tuple) else out
+            certify(circuit, release=release, **kwargs)
+            return out
+        return wrapper
+    return deco
+
+
+def keygen(key_dir=None, *, overwrite: bool = False) -> dict[str, str]:
+    """Generate your producer signing key (default ~/.quantbom/signing.key, 0600). See quantbom._sign."""
+    from . import _sign
+
+    return _sign.keygen(key_dir, overwrite=overwrite)
+
+
+def sign(bundle, key=None, *, strict: bool = False) -> dict[str, Any]:
+    """Sign a collected bundle as its producer; strict=True when it will be uploaded with privacy="strict"."""
+    from . import _sign
+
+    return _sign.sign(bundle, key, omit_refs=STRICT_WITHHELD_REFS if strict else ())
+
+
+def verify(path, *, certificate=None, keys_file=None, service_key=None) -> dict[str, Any]:
+    """Offline verification of a mirror directory, a collected bundle or a zip of either. See quantbom._verify."""
+    from . import _verify
+
+    return _verify.verify(path, certificate=certificate, keys_file=keys_file, service_key=service_key)
+
+
+def pin_keys(api_url: str | None = None, out=None) -> dict[str, Any]:
+    """Fetch the service's signing keys once and pin them as the local trust anchor for verify()."""
+    from . import _verify
+
+    return _verify.pin_keys(api_url or _config["api_url"], out)
+
+
+def _summarize(result: dict[str, Any]) -> None:
+    if result.get("ok"):
+        cert = result.get("certificate", {})
+        ver = result.get("verification", {})
+        _warn(
+            f"{result.get('release_id')}: {result.get('overall_status')} · "
+            f"cert {cert.get('certificate_id')} ({cert.get('overall_status')}) · "
+            f"verify {ver.get('verdict')} · credits left {result.get('credits_remaining')} · mirror {result.get('mirror')}"
+        )
+    else:
+        _warn(f"{result.get('release_id')}: not certified — {result.get('error')} (workflow continues)")
+
+
+def _safe(name: str) -> str:
+    return "".join(c if c.isalnum() or c in "._-@" else "_" for c in name)
+
+
+def _read_err(exc: urllib.error.HTTPError) -> dict[str, Any]:
+    try:
+        return json.loads(exc.read().decode("utf-8"))
+    except Exception:
+        return {}

quantbom/_bitorder.py

@@ -0,0 +1,121 @@
+"""Bit order for declared expected results (QBOM-BENCH-02).
+
+Results are measured on the translated Qiskit circuit, so measured bitstrings
+arrive in Qiskit's order: classical bit 0 is the RIGHTMOST character. Cirq,
+Braket and PennyLane print qubit 0 as the LEFTMOST character. Measured with
+each framework's own sampler, an X on qubit 0 of three qubits reads:
+
+    cirq, braket, pennylane   '100'
+    qrisp, qiskit             '001'
+
+A declaration written in the wrong order is not just an inconvenience. It
+fails correct releases — and it can pass wrong ones: '100' meant as "qubit 0
+flipped" matches a buggy circuit that flips qubit 2 instead.
+
+So expected results are read in the framework's own order by default and
+translated to the measured order before comparison; the declaration as
+written, and the order it was read in, are recorded in the hash-bound
+expected-distribution document. Qiskit and Qrisp need no translation.
+
+Declarations are also checked against the measured register width up front:
+a wrong-width key can never match a measured outcome, so it always signals a
+mistake and is better raised than recorded as a silent `exceeded`.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .frameworks import ADAPTERS
+
+# Frameworks whose own bitstrings put qubit 0 first — declared per adapter and
+# verified against each framework's own sampler by the conformance suite.
+QUBIT0_FIRST = {a.name for a in ADAPTERS if a.bit_order == "qubit0_first"}
+ORDERS = ("native", "qiskit")
+
+
+def measured_register(qiskit_circuit: Any) -> tuple[int, int]:
+    """(width, number of classical registers) exactly as the collector measures.
+
+    Mirrors the collector's runner: a circuit with no measurement gets
+    measure_all(), and the reported bitstring spans every classical bit.
+    """
+    circ = qiskit_circuit.copy()
+    if not any(inst.operation.name == "measure" for inst in circ.data):
+        circ.measure_all()
+    return circ.num_clbits, len(circ.cregs)
+
+
+def to_measured_order(
+    expected: dict[str, float],
+    source_format: str,
+    qiskit_circuit: Any,
+    order: str = "native",
+    *,
+    native_order: str | None = None,
+    measured_order: str = "qubit0_last",
+) -> tuple[dict[str, float], dict[str, Any]]:
+    """Return (distribution in measured order, declaration record).
+
+    `native_order` is how the framework's own reading of THIS input is ordered
+    (per input kind for Qrisp; the adapter's `bit_order_for`), defaulting to the
+    adapter's class-level order. `measured_order` is how the lowered circuit's
+    measured string is ordered — Qiskit's, unless the lowering allocates
+    classical bits in reverse (Jasp). A declaration is translated exactly when
+    the two differ.
+
+    Raises ValueError for a declaration that cannot be interpreted safely:
+    unknown order, non-binary or wrong-width keys, keys that collide once
+    normalised, or a translation on a multi-register circuit (where "qubit 0
+    first" no longer describes a single unambiguous string).
+    """
+    if order not in ORDERS:
+        raise ValueError(f"expected_order must be one of {ORDERS}, not {order!r}")
+    if native_order is None:
+        native_order = "qubit0_first" if source_format in QUBIT0_FIRST else "qubit0_last"
+    width, registers = measured_register(qiskit_circuit)
+
+    declared: dict[str, float] = {}
+    for raw_key, prob in expected.items():
+        key = str(raw_key).replace(" ", "")
+        if not key or set(key) - {"0", "1"}:
+            raise ValueError(f"expected outcome {raw_key!r} is not a bitstring of 0s and 1s")
+        if len(key) != width:
+            raise ValueError(
+                f"expected outcome {raw_key!r} has {len(key)} bits, but this circuit is measured "
+                f"over {width} classical bits — every outcome must be exactly {width} characters"
+            )
+        if key in declared:
+            raise ValueError(f"expected outcome {raw_key!r} duplicates another key once spaces are removed")
+        declared[key] = float(prob)
+
+    translate = order == "native" and native_order != measured_order
+    if translate and registers > 1:
+        raise ValueError(
+            f"this {source_format} circuit measures into {registers} classical registers, so "
+            "'qubit 0 first' does not define one unambiguous bitstring. Declare the expected "
+            "outcomes in measured (Qiskit) order and pass expected_order='qiskit'."
+        )
+
+    first = "qubit 0 is the leftmost character"
+    last = "qubit 0 is the rightmost character"
+    if translate:
+        measured = {k[::-1]: v for k, v in declared.items()}
+        record = {
+            "declared_order": f"native ({source_format}): {first if native_order == 'qubit0_first' else last}",
+            "declared_distribution": declared,
+            "translated": True,
+        }
+    else:
+        convention = (
+            "qiskit: classical bit 0 is the rightmost character"
+            if order == "qiskit"
+            else f"native ({source_format}): same convention as the measured order"
+        )
+        measured = dict(declared)
+        record = {"declared_order": convention, "translated": False}
+    record["measured_order"] = (
+        "qiskit: classical bit 0 is the rightmost character" if measured_order == "qubit0_last"
+        else "lowered circuit: classical bits allocated in reverse, so qubit 0 is the leftmost character"
+    )
+    record["width"] = width
+    return measured, record