quantbom 0.6.0__py3-none-any.whl

quantbom/_collect.py

@@ -0,0 +1,661 @@
+"""Bundled evidence collector for the QuantBOM SDK (self-contained — no server deps).
+
+Runs an actual Qrisp/Qiskit/OpenQASM circuit through the open-source toolchain and
+produces verifiable evidence (the QBOM):
+
+    Qrisp/Qiskit circuit ──.to_qiskit()──▶ qiskit.QuantumCircuit   (normalized IR)
+                                              │
+                  qiskit.qpy.dump() ──▶ circuit.qpy / transpiled.qpy  (REAL bytes)
+                                              │
+                         hashlib.sha256(bytes) ──▶ secqdevops:*-sha256  (REAL hash)
+
+Everything runs offline on stock Qiskit (+ Qrisp for Qrisp circuits) — no IBM
+account, no cloud. The hashes are of the actual file bytes, so the QuantBOM
+service (and the user, offline) can independently re-verify them.
+
+This is an internal module; use the public API in `quantbom` (certify/certified/wrap)
+or the `quantbom` CLI.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+from pathlib import Path
+from typing import Any
+
+
+# Self-contained hashing helpers (kept identical to the server's so digests match).
+def canonical_json(data: Any) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def sha256_bytes(raw: bytes) -> str:
+    return f"sha256:{hashlib.sha256(raw).hexdigest()}"
+
+
+BASIS_GATES = ["rz", "sx", "x", "cx", "measure"]
+SEED_TRANSPILER = 42
+
+
+def build_demo_circuit():
+    """A small, real Qrisp program: a 3-bit quantum adder (2 + 3)."""
+    from qrisp import QuantumFloat
+
+    a = QuantumFloat(3)
+    b = QuantumFloat(3)
+    a[:] = 2
+    b[:] = 3
+    c = a + b
+    return c.qs.compile()
+
+
+def get_qrisp_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("qrisp")
+    except Exception:
+        return "unknown"
+
+
+# QPY is not forward-readable: a Qiskit release writes its own newest QPY format
+# by default, and an older Qiskit refuses it ("QPY format version 18 isn't
+# supported"). Found 20 Oct 2026: a producer on qiskit 2.6 (QPY 18) uploaded to a
+# service on qiskit 2.5 (reads up to 17, held below 2.6 by qrisp), and the service
+# could not load the circuits to re-derive QNT-05 or re-execute them. Every Qiskit
+# the SDK supports (>=2.0) writes and reads QPY 13 (its QPY_COMPATIBILITY_VERSION),
+# so the bundle is written there; a circuit using a feature 13 cannot express
+# falls back to the native format, and the service then says it cannot load it.
+QPY_PORTABLE_VERSION = 13
+
+
+def _qpy_bytes(qiskit_circuit) -> bytes:
+    from qiskit import qpy
+
+    version = max(QPY_PORTABLE_VERSION, getattr(qpy, "QPY_COMPATIBILITY_VERSION", QPY_PORTABLE_VERSION))
+    buf = io.BytesIO()
+    try:
+        qpy.dump(qiskit_circuit, buf, version=version)
+    except Exception:  # a feature the portable format cannot express: the native format, readable by this Qiskit and newer
+        buf = io.BytesIO()
+        qpy.dump(qiskit_circuit, buf)
+    return buf.getvalue()
+
+
+def load_circuit(source: str, value: str | None) -> tuple[Any, str, Any, str]:
+    """Resolve any supported frontend down to the normalized IR.
+
+    Returns (qiskit_circuit, frontend_label, qrisp_circuit_or_None, source_format).
+    Every path lowers to a `qiskit.QuantumCircuit` — the QBOM normalized IR —
+    through the framework adapters.
+    """
+    from .frameworks import get as _adapter
+
+    if source == "qrisp-demo":
+        qiskit_circuit, label, native = _adapter("qrisp").lower(build_demo_circuit())
+        return qiskit_circuit, label, native, "qrisp"
+    if source in ("qpy", "qasm3", "qasm2"):
+        circ, label, fmt = _adapter("qiskit").load(source, value)
+        return circ, label, None, fmt
+    raise ValueError(f"unknown circuit source: {source}")
+
+
+def _circuit_metrics(qiskit_circuit, qrisp_circuit=None) -> dict[str, Any]:
+    """Structural metrics computed from the normalized IR (works for any frontend)."""
+    def safe(fn, default=0):
+        try:
+            return fn()
+        except Exception:
+            return default
+
+    metrics = {
+        "qubits": qiskit_circuit.num_qubits,
+        "depth": safe(lambda: qiskit_circuit.depth()),
+        "size": safe(lambda: qiskit_circuit.size()),
+        "t_depth": safe(lambda: qiskit_circuit.depth(lambda i: i.operation.name in ("t", "tdg"))),
+        "two_qubit_depth": safe(lambda: qiskit_circuit.depth(lambda i: len(i.qubits) > 1)),
+        "gate_counts": dict(safe(lambda: qiskit_circuit.count_ops(), {})),
+    }
+    if qrisp_circuit is not None:  # enrich with qrisp-native metrics when available
+        try:
+            cd = getattr(qrisp_circuit, "cnot_depth")
+            metrics["cnot_depth"] = cd() if callable(cd) else cd
+        except Exception:
+            pass
+    return metrics
+
+
+def _calibration_snapshot(backend, provider: str, backend_name: str, simulator: bool) -> dict[str, Any]:
+    """Best-effort device-calibration snapshot at execution time (F2.1).
+
+    Captures what the backend exposes — per-qubit T1/T2/frequency, readout
+    and gate errors, backend version, calibration timestamp — so hardware
+    evidence is tied to the actual device at the actual time (CEN/CENELEC
+    Roadmap §8.5, SI-traceable). Every field is optional: an ideal simulator
+    yields an honest minimal snapshot, never a fabricated one.
+    """
+    from datetime import datetime, timezone
+
+    snap: dict[str, Any] = {
+        "schema": "secqdevops.backend-calibration/v1",
+        "provider": provider, "backend": backend_name, "simulator": simulator,
+        # when this snapshot was taken (the run time); with the provider's
+        # calibration_last_update it gives the calibration's age at the run (Q1.3)
+        "captured_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "backend_version": None, "num_qubits": None, "qubits": [], "gates": {},
+    }
+    if backend is None:
+        snap["note"] = "no backend object available"
+        return snap
+    try:
+        version = str(getattr(backend, "backend_version", "") or "").strip()
+        snap["backend_version"] = version or None
+    except Exception:
+        pass
+    target = getattr(backend, "target", None)
+    if target is None:
+        snap["note"] = "backend exposes no target"
+        return snap
+    snap["num_qubits"] = getattr(target, "num_qubits", None)
+    for i, qp in enumerate(getattr(target, "qubit_properties", None) or []):
+        if qp is None:
+            continue
+        entry: dict[str, Any] = {"qubit": i}
+        for attr, key, scale in (("t1", "t1_us", 1e6), ("t2", "t2_us", 1e6), ("frequency", "frequency_ghz", 1e-9)):
+            value = getattr(qp, attr, None)
+            entry[key] = round(value * scale, 3) if isinstance(value, (int, float)) else None
+        try:
+            entry["readout_error"] = round(target["measure"][(i,)].error, 6)
+        except Exception:
+            pass
+        snap["qubits"].append(entry)
+    try:
+        for name in getattr(target, "operation_names", []):
+            errors = [p.error for p in target[name].values() if p is not None and getattr(p, "error", None) is not None]
+            if errors:
+                snap["gates"][name] = {"avg_error": round(sum(errors) / len(errors), 6), "instances": len(errors)}
+    except Exception:
+        pass
+    try:  # classic properties (IBM) carry the calibration timestamp
+        props_fn = getattr(backend, "properties", None)
+        if callable(props_fn):
+            last_update = getattr(props_fn(), "last_update_date", None)
+            if last_update:
+                snap["calibration_last_update"] = str(last_update)
+    except Exception:
+        pass
+    if simulator and not snap["qubits"]:
+        snap["note"] = "ideal simulator — no device calibration data"
+    return snap
+
+
+SEED_SIMULATOR = 1234
+SEED_GENERIC = 1234
+
+
+def _parse_time(value: Any):
+    """Provider timestamps come in several shapes; naive ones are taken as UTC."""
+    from datetime import datetime, timezone
+
+    if value is None:
+        return None
+    text = str(value).strip().replace("Z", "+00:00")
+    if " " in text and "T" not in text:
+        text = text.replace(" ", "T", 1)
+    try:
+        dt = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def calibration_age_hours(snapshot: dict[str, Any]) -> float | None:
+    """Hours between the provider's last calibration and the run; None when the
+    device reports no calibration time (simulators, synthetic devices)."""
+    last, captured = _parse_time(snapshot.get("calibration_last_update")), _parse_time(snapshot.get("captured_at"))
+    if last is None or captured is None:
+        return None
+    return max(0.0, (captured - last).total_seconds() / 3600.0)
+
+
+def _with_measurements(qiskit_circuit):
+    circ = qiskit_circuit.copy()
+    if not any(inst.operation.name == "measure" for inst in circ.data):
+        circ.measure_all()
+    return circ
+
+
+def _aer():
+    try:
+        from qiskit_aer import AerSimulator
+
+        return AerSimulator
+    except Exception:
+        return None
+
+
+SIMULATOR_ERROR_HANDLING = {  # local simulators return raw counts; nothing is corrected after the fact
+    "source": "local simulator: counts are raw samples of the simulated distribution",
+    "mitigation_status": "none", "mitigation": [], "suppression": [], "raw_counts": True,
+}
+
+
+def _ibm_error_handling(sampler) -> dict[str, Any]:
+    """What qiskit-ibm-runtime's SamplerV2 reports about error handling, from its
+    options as resolved at submission. SamplerV2 returns raw counts (readout
+    mitigation lives in the Estimator), so mitigation is `none`; dynamical
+    decoupling and twirling are error *suppression* and are listed when enabled.
+    Anything unreadable is `unknown`, never guessed."""
+    try:
+        opts = sampler.options
+        suppression = []
+        dd = getattr(opts, "dynamical_decoupling", None)
+        if dd is not None and getattr(dd, "enable", False):
+            suppression.append({"method": "dynamical_decoupling", "sequence": str(getattr(dd, "sequence_type", "")) or None})
+        tw = getattr(opts, "twirling", None)
+        if tw is not None and (getattr(tw, "enable_gates", False) or getattr(tw, "enable_measure", False)):
+            suppression.append({"method": "twirling", "gates": bool(getattr(tw, "enable_gates", False)),
+                                "measure": bool(getattr(tw, "enable_measure", False))})
+        return {"source": "qiskit-ibm-runtime SamplerV2 options as resolved at submission",
+                "mitigation_status": "none", "mitigation": [], "suppression": suppression, "raw_counts": True}
+    except Exception as exc:  # the provider's options could not be read: say so
+        return {"source": f"provider options unreadable ({type(exc).__name__})", "mitigation_status": "unknown",
+                "mitigation": [], "suppression": [], "raw_counts": None}
+
+
+def _not_run(shots: int, reason: str, provider: str, backend_name: str, status: str = "unsupported") -> dict[str, Any]:
+    """An honest record of a run that did not happen: no counts, and why."""
+    return {"shots": shots, "counts": {}, "status": status, "reason": reason, "provider": provider,
+            "backend_name": backend_name, "simulator": True, "execution_target": "simulator",
+            "noise": "n/a", "job_id": None, "session_id": None,
+            "error_handling": {**SIMULATOR_ERROR_HANDLING, "source": "no run took place", "raw_counts": None}}
+
+
+def _run_basic_simulator(qiskit_circuit, shots: int = 1024, dynamic: bool = False) -> dict[str, Any]:
+    """Local, noiseless execution: Qiskit's BasicSimulator, or qiskit-aer for
+    dynamic circuits (BasicSimulator cannot run classical control flow)."""
+    from qiskit import transpile
+
+    if dynamic:
+        AerSimulator = _aer()
+        if AerSimulator is None:
+            return _not_run(shots, "dynamic circuits need qiskit-aer to execute locally "
+                                   "(pip install 'quantbom[sim]'); Qiskit's BasicSimulator cannot run classical control flow",
+                            "qiskit-aer", "aer_simulator")
+        backend, provider, name = AerSimulator(), "qiskit-aer", "aer_simulator"
+        run_kw = {"seed_simulator": SEED_SIMULATOR}
+    else:
+        from qiskit.providers.basic_provider import BasicSimulator
+
+        backend, provider, name = BasicSimulator(), "qiskit", "basic_simulator"
+        run_kw = {"seed_simulator": SEED_SIMULATOR}  # reproducible local evidence (Q2.4)
+    try:
+        tqc = transpile(_with_measurements(qiskit_circuit), backend, seed_transpiler=SEED_TRANSPILER)
+        counts = backend.run(tqc, shots=shots, **run_kw).result().get_counts()
+    except Exception as exc:  # recorded, never hidden: the run did not happen
+        out = _not_run(shots, f"local simulation failed: {type(exc).__name__}: {exc}", provider, name, status="failed")
+        out["calibration"] = _calibration_snapshot(backend, provider, name, True)
+        return out
+    out = {"shots": shots, "counts": {str(k): int(v) for k, v in counts.items()}, "status": "completed",
+           "provider": provider, "backend_name": name, "simulator": True, "execution_target": "simulator",
+           "noise": "none (ideal simulator)", "job_id": None, "session_id": None,
+           "error_handling": dict(SIMULATOR_ERROR_HANDLING)}
+    out["calibration"] = _calibration_snapshot(backend, provider, name, True)
+    return out
+
+
+def _run_generic_backend(qiskit_circuit, shots: int = 1024, dynamic: bool = False) -> dict[str, Any]:
+    """A synthetic, seeded device (Qiskit's GenericBackendV2): realistic coupling
+    map, basis gates and calibration-like error rates — but no real device.
+    With qiskit-aer its noise model is simulated; without it the run is ideal.
+    Every record says which, and that the calibration is synthetic."""
+    from qiskit import transpile
+    from qiskit.providers.fake_provider import GenericBackendV2
+
+    n = max(int(qiskit_circuit.num_qubits), 2)
+    device = GenericBackendV2(num_qubits=n, seed=SEED_GENERIC, control_flow=True)
+    AerSimulator = _aer()
+    if AerSimulator is not None:
+        executor, provider, name = AerSimulator.from_backend(device), "qiskit-aer", f"aer_simulator({device.name})"
+        noise = f"synthetic noise model of {device.name} (GenericBackendV2, seed {SEED_GENERIC})"
+        run_kw = {"seed_simulator": SEED_SIMULATOR}
+    elif dynamic:
+        return _not_run(shots, "dynamic circuits need qiskit-aer to execute locally (pip install 'quantbom[sim]')",
+                        "qiskit", device.name)
+    else:
+        executor, provider, name = device, "qiskit", device.name
+        noise = "none — qiskit-aer not installed, so the synthetic device ran ideally"
+        run_kw = {}
+    calibration = _calibration_snapshot(device, "qiskit-generic", device.name, True)
+    calibration["synthetic"] = True
+    calibration["note"] = f"GenericBackendV2 synthetic calibration (seed {SEED_GENERIC}) — not a real device"
+    try:
+        tqc = transpile(_with_measurements(qiskit_circuit), device, seed_transpiler=SEED_TRANSPILER)
+        counts = executor.run(tqc, shots=shots, **run_kw).result().get_counts()
+    except Exception as exc:
+        out = _not_run(shots, f"local simulation failed: {type(exc).__name__}: {exc}", provider, name, status="failed")
+        out["calibration"] = calibration
+        return out
+    return {"shots": shots, "counts": {str(k): int(v) for k, v in counts.items()}, "status": "completed",
+            "provider": provider, "backend_name": name, "simulator": True, "execution_target": "simulator",
+            "noise": noise, "job_id": None, "session_id": None, "calibration": calibration,
+            "error_handling": {**SIMULATOR_ERROR_HANDLING,
+                               "source": "local simulator with a synthetic noise model: counts are raw samples, nothing corrected"}}
+
+
+def _run_ibm_runtime(qiskit_circuit, shots: int = 1024) -> dict[str, Any]:
+    """Real IBM Quantum execution via qiskit-ibm-runtime (needs the [ibm] extra + saved creds)."""
+    from qiskit import transpile
+    from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2
+
+    service = QiskitRuntimeService()
+    backend = service.least_busy(operational=True, simulator=False)
+    circ = qiskit_circuit.copy()
+    if not any(inst.operation.name == "measure" for inst in circ.data):
+        circ.measure_all()
+    tqc = transpile(circ, backend, seed_transpiler=SEED_TRANSPILER)
+    sampler = SamplerV2(mode=backend)
+    error_handling = _ibm_error_handling(sampler)
+    job = sampler.run([tqc], shots=shots)
+    result = job.result()
+    try:
+        counts = {str(k): int(v) for k, v in result[0].data.meas.get_counts().items()}
+    except Exception:
+        counts = {}
+    calibration = _calibration_snapshot(backend, "ibm", backend.name, False)
+    try:  # best-effort job receipt (usage/timestamps) — never blocks collection
+        metrics = job.metrics()
+        calibration["job_receipt"] = {
+            "job_id": job.job_id(),
+            "timestamps": metrics.get("timestamps"),
+            "usage": metrics.get("usage"),
+        }
+    except Exception:
+        calibration["job_receipt"] = {"job_id": job.job_id()}
+    return {
+        "shots": shots, "counts": counts, "status": "completed", "provider": "ibm", "backend_name": backend.name,
+        "simulator": False, "execution_target": "hardware", "noise": "real device",
+        "job_id": job.job_id(), "session_id": getattr(job, "session_id", None),
+        "calibration": calibration, "error_handling": error_handling,
+    }
+
+
+def _run_backend(qiskit_circuit, backend_choice: str = "basic", shots: int = 1024, dynamic: bool = False) -> dict[str, Any]:
+    """basic: local ideal simulator · generic: synthetic seeded device (GenericBackendV2)
+    · ibm: real IBM hardware when credentials allow, else the local simulator (recorded)."""
+    if backend_choice == "ibm":
+        try:
+            return _run_ibm_runtime(qiskit_circuit, shots)
+        except Exception as exc:  # graceful fallback keeps the pipeline offline-runnable
+            out = _run_basic_simulator(qiskit_circuit, shots, dynamic)
+            out["note"] = f"IBM runtime unavailable, used the local simulator: {exc}"
+            return out
+    if backend_choice == "generic":
+        return _run_generic_backend(qiskit_circuit, shots, dynamic)
+    if backend_choice != "basic":
+        raise ValueError(f"unknown backend {backend_choice!r} (basic, generic, ibm)")
+    return _run_basic_simulator(qiskit_circuit, shots, dynamic)
+
+
+def collect(
+    release_id: str,
+    out_dir: Path,
+    qiskit_circuit=None,
+    *,
+    frontend_label: str = "qrisp",
+    qrisp_circuit=None,
+    source_format: str = "qrisp",
+    backend_choice: str = "basic",
+    equivalence_check: bool = False,
+    expected_distribution: dict[str, float] | None = None,
+    expected_tolerance: float = 0.05,
+    conversion_fidelity: dict[str, Any] | None = None,
+    expected_declaration: dict[str, Any] | None = None,
+    native_export: tuple[str, str] | None = None,
+    native_result: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Run the harness actions over one circuit and write its QBOM.
+
+    Each regulation-mapped action (sdk/quantbom/actions/) writes its own
+    artifacts and returns the properties it emits; they are placed in the QBOM
+    by the declared layout, which also rejects two actions emitting one property.
+    """
+    if qiskit_circuit is None:  # default: the Qrisp demo, for backward compatibility
+        qiskit_circuit, frontend_label, qrisp_circuit, source_format = load_circuit("qrisp-demo", None)
+    from qiskit import __version__ as qiskit_version
+
+    from . import frameworks
+    from ._circuit import inspect_circuit, refuse_dynamic, require_closed
+    from .actions import assemble, run_all
+    from .actions.base import Context
+
+    # Preconditions, before any evidence is written (K0): an open circuit is
+    # refused; a dynamic one is accepted and recorded — for adapters that
+    # claim dynamic support (file inputs are Qiskit's own and always do).
+    circuit_info = inspect_circuit(qiskit_circuit)
+    require_closed(circuit_info)
+    adapter = frameworks.get(source_format)
+    if circuit_info["dynamic"] and adapter is not None and not adapter.supports_dynamic:
+        refuse_dynamic(circuit_info["dynamic_features"], source_format)
+
+    ctx = Context(
+        release_id=release_id, out_dir=out_dir, qiskit_circuit=qiskit_circuit, qrisp_circuit=qrisp_circuit,
+        frontend_label=frontend_label, source_format=source_format, backend_choice=backend_choice,
+        equivalence_check=equivalence_check, expected_distribution=expected_distribution,
+        expected_tolerance=expected_tolerance, expected_declaration=expected_declaration,
+        conversion_fidelity=conversion_fidelity, qiskit_version=qiskit_version, qrisp_version=get_qrisp_version(),
+        native_export=native_export, native_result=native_result, circuit_info=circuit_info,
+    )
+    results = run_all(ctx)
+    results.append(_record_outcomes(ctx, results))
+    s = ctx.state
+    sbom = _build_sbom(release_id, ctx.qrisp_version, qiskit_version, s["metrics"], assemble(results), source_format)
+    sbom_path = out_dir / "sbom.cdx.json"
+    _write_json(sbom_path, sbom)
+    s["action_results"] = results
+
+    return {
+        "release_id": release_id,
+        "frontend": frontend_label,
+        "source_format": source_format,
+        "backend": s["runtime_result"]["backend_name"],
+        "qiskit_version": qiskit_version,
+        "circuit_metrics": s["metrics"],
+        "circuit_sha256": s["circuit_sha"],
+        "transpiled_sha256": s["transpiled_sha"],
+        "qasm_sha256": s["qasm_sha"],
+        "benchmark_sha256": s["benchmark_sha"],
+        "qir_sha256": s["qir_sha"],
+        "equivalence_verdict": s["equivalence_verdict"],
+        "conversion_fidelity_verdict": s["conversion_verdict"],
+        "result_fidelity": s["fidelity_summary"],
+        "calibration_sha256": s["calibration_sha"],
+        "circuit_qpy_bytes": len(s["circuit_qpy"]),
+        "transpiled_qpy_bytes": len(s["transpiled_qpy"]),
+        "sbom_path": str(sbom_path),
+    }
+
+
+def _record_outcomes(ctx, results) -> Any:
+    """record_outcomes — what every action did, and why, as hash-bound evidence.
+
+    Lets the gate explain each N-A ("not requested", "unsupported: mqt.qcec is
+    not installed", "no adapter-side translation") instead of a bare N-A. The
+    explanation is informational; verdicts never depend on it.
+    """
+    from .actions import HARNESS_VERSION
+    from .actions.base import PRODUCED, ActionResult
+
+    log = {
+        "schema": "secqdevops.harness-log/v1",
+        "release_id": ctx.release_id,
+        "harness_version": HARNESS_VERSION,
+        "framework": ctx.source_format,
+        "actions": [{"id": r.action, "outcome": r.outcome, **({"reason": r.reason} if r.reason else {})}
+                    for r in results],
+    }
+    ctx.quantum_dir.mkdir(parents=True, exist_ok=True)
+    log_sha = _write_json(ctx.quantum_dir / "harness-log.json", log)
+    return ActionResult("record_outcomes", PRODUCED, [
+        {"name": "secqdevops:harness-version", "value": HARNESS_VERSION},
+        {"name": "secqdevops:harness-log-ref", "value": "quantum/harness-log.json"},
+        {"name": "secqdevops:harness-log-sha256", "value": log_sha},
+    ])
+
+
+def sdk_version() -> str:
+    """This SDK's version, for the QBOM's metadata.tools and the provenance builder.
+
+    In a source checkout (PYTHONPATH=sdk) sdk/pyproject.toml is the single source
+    of truth (RELEASING.md); installed package metadata can be a stale earlier
+    install there, so it is read only when no pyproject sits beside the package.
+    """
+    import re
+
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    if pyproject.is_file():
+        text = pyproject.read_text(encoding="utf-8")
+        if re.search(r'^name\s*=\s*"quantbom"', text, re.M) and (m := re.search(r'^version\s*=\s*"([^"]+)"', text, re.M)):
+            return m.group(1)
+    try:
+        from importlib.metadata import version as _dist_version
+
+        return _dist_version("quantbom")
+    except Exception:
+        return "unknown"
+
+
+def split_release(release_id: str) -> tuple[str, str | None]:
+    """`my-app@1.2.3` -> ("my-app", "1.2.3"); without a version part, (release_id, None).
+
+    Split at the last "@" so a scoped name (`@scope/app@1.0`) keeps its own.
+    """
+    name, sep, version = release_id.rpartition("@")
+    if sep and name and version:
+        return name, version
+    return release_id, None
+
+
+def _release_purl(name: str, version: str | None) -> str:
+    """pkg:generic purl for the release: each name segment and the version
+    percent-encoded (purl spec), so `owner/repo@sha` stays one valid purl."""
+    from urllib.parse import quote
+
+    path = "/".join(quote(seg, safe="") for seg in name.split("/") if seg) or quote(name, safe="")
+    return f"pkg:generic/{path}" + (f"@{quote(version, safe='')}" if version else "")
+
+
+def _collection_timestamp() -> str:
+    """When the evidence was collected (UTC). SOURCE_DATE_EPOCH, the
+    reproducible-builds convention, pins it for byte-reproducible bundles."""
+    import os
+    from datetime import datetime, timezone
+
+    epoch = os.environ.get("SOURCE_DATE_EPOCH", "").strip()
+    moment = datetime.fromtimestamp(int(epoch), timezone.utc) if epoch.isdigit() else datetime.now(timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _release_component(release_id: str) -> dict[str, Any]:
+    """metadata.component: the release as the producer named it.
+
+    It once read `quantum-workload-<release_id>`, version 1.0.0 and an
+    Apache-2.0 licence for every release: a version the release does not have,
+    a malformed purl (`pkg:generic/app@1.2.3@1.0.0`) and a licence nothing
+    evidenced. No licence is declared now: the collector cannot know the
+    producer's, and asserting one would be an unevidenced claim.
+    """
+    name, version = split_release(release_id)
+    return {"type": "application", "name": name, **({"version": version} if version else {}),
+            "purl": _release_purl(name, version)}
+
+
+def _frontend_component(source_format: str) -> dict[str, Any] | None:
+    """The authoring framework as an SBOM component.
+
+    The component list must name the framework the release was actually written
+    in: hardcoding qrisp+qiskit once listed Qrisp for Cirq/Braket/PennyLane
+    releases that never used it, and omitted the framework they did use — an
+    inaccurate inventory under CRA Annex I Part II(1), and a framework no CVE
+    scan would see. The distribution and licence come from the framework's
+    adapter. None when the input was already Qiskit (in-memory, QPY or
+    OpenQASM), since qiskit is always listed as the IR.
+    """
+    from .frameworks import get as _adapter
+
+    adapter = _adapter(source_format)
+    if adapter is None or adapter.name == "qiskit":
+        return None
+    dist, licence = adapter.component, adapter.license
+    try:
+        from importlib.metadata import version as _dist_version
+
+        ver = _dist_version(dist)
+    except Exception:
+        ver = "unknown"
+    return {
+        "type": "library",
+        "name": dist,
+        "version": ver,
+        "purl": f"pkg:pypi/{dist}@{ver}",
+        "licenses": [{"license": {"id": licence}}],
+        "properties": [{"name": "secqdevops:component-layer", "value": "programming"}],
+    }
+
+
+def _build_sbom(
+    release_id: str,
+    qrisp_version: str,
+    qiskit_version: str,
+    metrics: dict[str, Any],
+    properties: list[dict[str, str]],
+    source_format: str = "qrisp",
+) -> dict[str, Any]:
+    serial = "urn:uuid:" + sha256_bytes(release_id.encode("utf-8")).split(":", 1)[1][:32]
+    serial = f"urn:uuid:{serial[9:17]}-{serial[17:21]}-{serial[21:25]}-{serial[25:29]}-{serial[29:41]}"
+    return {
+        "bomFormat": "CycloneDX",
+        "specVersion": "1.7",
+        "serialNumber": serial,
+        "version": 1,
+        "metadata": {
+            "timestamp": _collection_timestamp(),
+            "tools": {
+                "components": [
+                    # The generator is the quantbom SDK, whatever the framework (the
+                    # label once read "secqdevops-qrisp-evidence 0.1.0" for every release).
+                    {"type": "application", "name": "quantbom", "version": (v := sdk_version()),
+                     "purl": f"pkg:pypi/quantbom@{v}",
+                     "description": "QuantBOM SDK: SecQDevOps MOD-08 evidence collector"}
+                ]
+            },
+            "component": _release_component(release_id),
+            "properties": properties,
+        },
+        "components": [
+            *([fc] if (fc := _frontend_component(source_format)) else []),
+            {
+                "type": "library",
+                "name": "qiskit",
+                "version": qiskit_version,
+                "purl": f"pkg:pypi/qiskit@{qiskit_version}",
+                "licenses": [{"license": {"id": "Apache-2.0"}}],
+                "properties": [{"name": "secqdevops:component-layer", "value": "programming"}],
+            },
+        ],
+    }
+
+
+def _write_json(path: Path, data: Any) -> str:
+    """Write `data` as JSON and return the sha256 of the exact bytes written.
+
+    Returning the digest lets callers bind the artifact into the QBOM as
+    hash-verified evidence. `ensure_ascii=True` keeps the encoded bytes
+    identical to what `write_text` puts on disk, so the digest matches what
+    the server re-derives.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(data, indent=2, ensure_ascii=True) + "\n"
+    path.write_text(payload, encoding="utf-8")
+    return sha256_bytes(payload.encode("utf-8"))