quantbom 0.6.0__py3-none-any.whl

quantbom/actions/layout.py

@@ -0,0 +1,118 @@
+"""The QBOM property layout — the order properties appear in `metadata.properties`.
+
+Actions emit properties in whatever order suits them; the collector places them
+by this table, so the SBOM is byte-stable and adding a property is an explicit
+decision. A property missing from this table is an error, not an afterthought.
+"""
+PROPERTY_ORDER = (
+    "secqdevops:provenance-ref",
+    "secqdevops:signature-ref",
+    "secqdevops:provenance-artifact-ref",
+    "secqdevops:signature-artifact-ref",
+    "secqdevops:quantum-stack",
+    "secqdevops:normalized-ir",
+    "secqdevops:source-format",
+    "secqdevops:circuit-format",
+    "secqdevops:circuit-artifact-ref",
+    "secqdevops:circuit-sha256",
+    "secqdevops:transpiled-circuit-ref",
+    "secqdevops:transpiled-circuit-sha256",
+    "secqdevops:qasm-program-ref",
+    "secqdevops:qasm-program-sha256",
+    "secqdevops:qir-program-ref",
+    "secqdevops:qir-program-sha256",
+    "secqdevops:qir-profile",
+    "secqdevops:transpile-report-ref",
+    "secqdevops:backend-provider",
+    "secqdevops:backend-name",
+    "secqdevops:execution-mode",
+    "secqdevops:execution-target",
+    "secqdevops:transpile-profile-hash",
+    "secqdevops:backend-target-ref",
+    "secqdevops:backend-target-sha256",
+    "secqdevops:calibration-ref",
+    "secqdevops:calibration-sha256",
+    "secqdevops:calibration-captured-at",
+    "secqdevops:calibration-age-hours",
+    "secqdevops:error-handling-ref",
+    "secqdevops:error-handling-sha256",
+    "secqdevops:error-mitigation",
+    "secqdevops:runtime-job-id",
+    "secqdevops:runtime-job-ref",
+    "secqdevops:runtime-job-sha256",
+    "secqdevops:runtime-job-status",
+    "secqdevops:result-summary-ref",
+    "secqdevops:result-summary-sha256",
+    "secqdevops:qubit-count",
+    "secqdevops:circuit-depth",
+    "secqdevops:two-qubit-depth",
+    "secqdevops:t-depth",
+    "secqdevops:gate-count",
+    "secqdevops:benchmark-ref",
+    "secqdevops:benchmark-sha256",
+    "secqdevops:layer-model-ref",
+    "secqdevops:vocabulary-ref",
+    "secqdevops:cyclonedx-edition",
+    "secqdevops:qbom-profile-version",
+    "secqdevops:circuit-layer",
+    "secqdevops:circuit-dynamic",
+    "secqdevops:transpiled-circuit-layer",
+    "secqdevops:backend-target-layer",
+    "secqdevops:runtime-job-layer",
+    "secqdevops:equivalence-ref",
+    "secqdevops:equivalence-sha256",
+    "secqdevops:equivalence-verdict",
+    "secqdevops:equivalence-tool",
+    "secqdevops:equivalence-kind",
+    "secqdevops:expected-distribution-ref",
+    "secqdevops:expected-distribution-sha256",
+    "secqdevops:result-tvd",
+    "secqdevops:result-tolerance",
+    "secqdevops:result-fidelity-verdict",
+    "secqdevops:result-confidence",
+    "secqdevops:result-sampling-error",
+    "secqdevops:result-shots-required",
+    "secqdevops:conversion-fidelity-ref",
+    "secqdevops:conversion-fidelity-sha256",
+    "secqdevops:conversion-fidelity-verdict",
+    "secqdevops:conversion-fidelity-method",
+    "secqdevops:native-program-ref",
+    "secqdevops:native-program-sha256",
+    "secqdevops:native-program-format",
+    "secqdevops:native-result-ref",
+    "secqdevops:native-result-sha256",
+    "secqdevops:native-result-verdict",
+    "secqdevops:native-result-tvd",
+    "secqdevops:qir-consistency-ref",
+    "secqdevops:qir-consistency-sha256",
+    "secqdevops:qir-consistency-verdict",
+    "secqdevops:runtime-session-id",
+    "secqdevops:provider-job-id",
+    "secqdevops:cnot-depth",
+    "secqdevops:ir-standard",
+    "secqdevops:harness-version",
+    "secqdevops:harness-log-ref",
+    "secqdevops:harness-log-sha256",
+)
+
+
+def assemble(results) -> list[dict[str, str]]:
+    """Merge every action's properties into the canonical layout.
+
+    Raises if two actions emit the same property (a collision like the one that
+    once silently dropped result-fidelity evidence) or if a property has no
+    place in the layout.
+    """
+    owner: dict[str, str] = {}
+    values: dict[str, str] = {}
+    for result in results:
+        for prop in result.properties:
+            name = prop["name"]
+            if name in owner:
+                raise RuntimeError(f"{name} emitted by both {owner[name]!r} and {result.action!r}")
+            owner[name] = result.action
+            values[name] = prop["value"]
+    unplaced = sorted(set(values) - set(PROPERTY_ORDER))
+    if unplaced:
+        raise RuntimeError(f"properties with no place in the QBOM layout: {unplaced}")
+    return [{"name": n, "value": values[n]} for n in PROPERTY_ORDER if n in values]

quantbom/actions/prove_equivalence.py

@@ -0,0 +1,225 @@
+"""prove_equivalence — the compiled circuit computes the same function as the source (feeds QNT-05).
+
+The collector only RECORDS the checker's verdict, including `not_equivalent`
+(honesty over convenience); the gate judges it.
+
+Kinds of equivalence (decision 7 Oct 2026, `secqdevops:equivalence-kind`):
+  unitary        the compiled circuit implements the same unitary (up to global phase)
+  observational  the unitaries differ, but by nothing any measurement can observe —
+                 identical measurement statistics (QCEC partial equivalence). A
+                 measurement-aware optimiser (Qiskit level 3) legitimately produces
+                 this; the full check alone would call a correct compilation wrong.
+                 Only attempted for circuits whose measurements are all final.
+  dynamic        a dynamic circuit, compared under QCEC's deferred-measurement
+                 transformation (see verify_dynamic)
+"""
+from __future__ import annotations
+
+import json
+
+from .base import NOT_REQUESTED, PRODUCED, UNSUPPORTED, ActionResult, Context
+
+ID = "prove_equivalence"
+
+
+def run(ctx: Context) -> ActionResult:
+    ctx.state["equivalence_verdict"] = None
+    if not ctx.equivalence_check:
+        return ActionResult(ID, NOT_REQUESTED, reason="equivalence proof not requested")
+    try:
+        from importlib.metadata import version as _pkg_version
+
+        from mqt import qcec
+    except ImportError:
+        return ActionResult(ID, UNSUPPORTED, reason="mqt.qcec is not installed (pip install 'quantbom[verify]')")
+    from .. import _collect as C
+
+    dynamic = bool(ctx.circuit_info.get("dynamic"))
+    dynamic_detail = None
+    partial_detail = None
+    kind = "dynamic" if dynamic else "unitary"
+    try:
+        if dynamic:
+            # dynamic circuits: QCEC defers measurements and turns classical
+            # control into quantum control before comparing (decision 2 Oct 2026)
+            result, dynamic_detail = verify_dynamic(qcec, ctx.qiskit_circuit, ctx.state["transpiled"])
+        else:
+            result = qcec.verify(ctx.qiskit_circuit, ctx.state["transpiled"])
+            if _criterion(result) == "not_equivalent" and final_measurements(ctx.qiskit_circuit):
+                # the unitaries differ: do the differences reach any measurement?
+                result, kind, partial_detail = verify_observational(qcec, ctx.qiskit_circuit, ctx.state["transpiled"], result)
+    except Exception as err:  # contained: one undecidable proof must never abort the collection
+        return ActionResult(ID, UNSUPPORTED,
+                            reason=f"mqt.qcec could not check this circuit: {type(err).__name__}: {str(err)[:200]}")
+    criterion = _criterion(result)
+    if result.considered_equivalent() and not (dynamic_detail or {}).get("unverified_gates"):
+        verdict = "equivalent"
+    elif criterion == "not_equivalent":
+        verdict = "not_equivalent"
+    else:  # timeout / no_information / a decomposition step not verified: declared but non-probative
+        verdict = "inconclusive"
+    tool = f"mqt.qcec@{_pkg_version('mqt.qcec')}"
+    method = "mqt.qcec verify() default portfolio (decision diagrams + ZX-calculus)"
+    if dynamic:
+        method += "; dynamic circuit transformed (deferred measurement, classical -> quantum control)"
+    if dynamic_detail and dynamic_detail.get("decomposed_source"):
+        method += ("; source decomposed to the basis at optimization level 0 before the comparison, each branch "
+                   "gate's decomposition verified separately up to global phase — the deferred-measurement model "
+                   "is sensitive to the global phase of gates inside classical branches (z vs rz(pi))")
+    if kind == "observational":
+        method += ("; observational equivalence (QCEC partial equivalence): the unitaries differ, but by nothing "
+                   f"the {partial_detail['measured_qubits']} measured qubit(s) can observe — identical measurement statistics; "
+                   f"partial check: {PARTIAL_CHECKERS}")
+    report = {
+        "schema": "secqdevops.equivalence/v1",
+        "release_id": ctx.release_id,
+        "tool": tool,
+        "method": method,
+        "criterion": criterion,
+        "verdict": verdict,
+        "equivalence_kind": kind,
+        "circuits": {"source": "quantum/circuit.qpy", "transpiled": "quantum/transpiled.qpy"},
+        **({"dynamic_check": dynamic_detail} if dynamic_detail else {}),
+        **({"partial_check": partial_detail} if partial_detail else {}),
+    }
+    raw = (json.dumps(report, indent=2, ensure_ascii=True) + "\n").encode("utf-8")
+    ctx.quantum_dir.mkdir(parents=True, exist_ok=True)
+    (ctx.quantum_dir / "equivalence-report.json").write_bytes(raw)
+    ctx.state["equivalence_verdict"] = verdict
+
+    props = [
+        {"name": "secqdevops:equivalence-ref", "value": "quantum/equivalence-report.json"},
+        {"name": "secqdevops:equivalence-sha256", "value": C.sha256_bytes(raw)},
+        {"name": "secqdevops:equivalence-verdict", "value": verdict},
+        {"name": "secqdevops:equivalence-tool", "value": tool},
+        {"name": "secqdevops:equivalence-kind", "value": kind},
+    ]
+    return ActionResult(ID, PRODUCED, props)
+
+
+def _criterion(result) -> str:
+    return str(result.equivalence).split(".")[-1]
+
+
+def final_measurements(circuit) -> bool:
+    """True when the circuit measures at least one qubit and every measurement is
+    final (nothing but barriers after a measurement on its qubit) — the shape on
+    which measurement statistics are a meaningful notion of equivalence."""
+    measured: set = set()
+    index = {q: i for i, q in enumerate(circuit.qubits)}
+    for inst in circuit.data:
+        name = inst.operation.name
+        qubits = [index[q] for q in inst.qubits]
+        if name == "measure":
+            measured.update(qubits)
+        elif name != "barrier" and any(q in measured for q in qubits):
+            return False
+    return bool(measured)
+
+
+# The partial check runs QCEC's portfolio without the ZX-calculus checker. ZX does not
+# support partial equivalence (QCEC refuses method="zx" with it), yet the default
+# portfolio still runs it: it compares the full unitaries, which are known to differ
+# here, and says probably_not_equivalent. When that answer arrived before the decision
+# diagrams', it conflicted with the simulation checker's "probably equivalent" and QCEC
+# returned no_information — a correct level-3 compilation declared inconclusive in about
+# 1 run in 100 (measured 24 Oct 2026, mqt.qcec 3.11.0). Without ZX the alternating
+# decision-diagram checker, which is complete, decides every time.
+PARTIAL_CHECKERS = "decision diagrams (alternating) + simulation; ZX-calculus off (it does not support partial equivalence)"
+
+
+def partial_check(qcec, source, compiled):
+    """QCEC partial (observational) equivalence, the one configuration producer, service and drift sentinel share."""
+    return qcec.verify(source, compiled, check_partial_equivalence=True, run_zx_checker=False)
+
+
+def verify_observational(qcec, source, transpiled, unitary_result):
+    """Re-check `not_equivalent` circuits for identical measurement statistics.
+
+    QCEC's partial equivalence treats measured qubits as the outputs that count
+    and ignores what no measurement observes (phases before a measurement,
+    unmeasured qubits). Returns (result, kind, detail): kind "observational" when
+    the partial check holds, otherwise the original result and "unitary".
+    """
+    second = partial_check(qcec, source, transpiled)
+    measured = len({q for inst in source.data if inst.operation.name == "measure" for q in inst.qubits})
+    detail = {
+        "unitary_criterion": _criterion(unitary_result),
+        "partial_criterion": _criterion(second),
+        "measured_qubits": measured,
+        "total_qubits": source.num_qubits,
+        "checkers": PARTIAL_CHECKERS,
+    }
+    if second.considered_equivalent():
+        return second, "observational", detail
+    if _criterion(second) != "not_equivalent":
+        # the partial check could not decide (no_information / timeout): no evidence either
+        # way, so the verdict is inconclusive (QNT-05 N-A), never a refutation. Found 20 Oct
+        # 2026 in CI: a correct level-3 compilation was declared not_equivalent and the
+        # service's re-derivation rightly disagreed.
+        # The drift sentinel already read it this way (_drift.meaning).
+        return second, "observational", detail
+    return unitary_result, "unitary", detail
+
+
+def _collect_branch_ops(circuit, inside: bool, found: dict) -> None:
+    for inst in circuit.data:
+        op = inst.operation
+        blocks = getattr(op, "blocks", None)
+        if blocks:
+            for block in blocks:
+                _collect_branch_ops(block, True, found)
+        elif inside and op.name not in ("measure", "reset", "barrier", "delay"):
+            key = (op.name, tuple(round(float(p), 12) for p in op.params if isinstance(p, (int, float))), op.num_qubits)
+            found.setdefault(key, op)
+
+
+def verify_dynamic(qcec, source, transpiled):
+    """QCEC on a dynamic circuit, with its one known blind spot closed.
+
+    QCEC's deferred-measurement transformation turns a classical branch into
+    quantum control. A gate's global phase is irrelevant under classical
+    control but becomes a relative phase under quantum control, so a body that
+    transpiles `z` to `rz(pi)` is reported `not_equivalent` although the
+    dynamic circuits agree (found 5 Oct 2026, mqt.qcec 3.10.1). The fix keeps
+    every step machine-checked: on `not_equivalent`, (1) decompose the source
+    to the basis at optimization level 0 (gate definitions only, no
+    optimisation), (2) verify each distinct gate inside a branch against its
+    own decomposition with QCEC in static mode (equivalent up to global phase
+    is exactly what classical control permits), (3) compare the decomposed
+    source with the transpiled circuit under the transformation. Equivalence
+    follows only if (2) and (3) both hold; a failed (2) makes the result
+    inconclusive, a failed (3) is a real `not_equivalent`.
+
+    Returns (result, detail-or-None); detail is recorded in the report.
+    """
+    from qiskit import QuantumCircuit, transpile
+
+    from .. import _collect as C
+
+    first = qcec.verify(source, transpiled, transform_dynamic_circuit=True)
+    if first.considered_equivalent() or _criterion(first) != "not_equivalent":
+        return first, None
+    decomposed = transpile(source, basis_gates=C.BASIS_GATES, optimization_level=0, seed_transpiler=C.SEED_TRANSPILER)
+    ops: dict = {}
+    _collect_branch_ops(source, False, ops)
+    gate_checks = []
+    unverified = []
+    for (name, params, n), op in sorted(ops.items(), key=lambda kv: kv[0][0]):
+        single = QuantumCircuit(n)
+        single.append(op, range(n))
+        single_decomposed = transpile(single, basis_gates=C.BASIS_GATES, optimization_level=0, seed_transpiler=C.SEED_TRANSPILER)
+        check = qcec.verify(single, single_decomposed)
+        gate_checks.append({"gate": name, "params": list(params), "criterion": _criterion(check)})
+        if not check.considered_equivalent():
+            unverified.append(name)
+    second = qcec.verify(decomposed, transpiled, transform_dynamic_circuit=True)
+    detail = {
+        "first_criterion": _criterion(first),
+        "decomposed_source": True,
+        "branch_gate_decompositions": gate_checks,
+        "decomposed_criterion": _criterion(second),
+    }
+    if unverified:
+        detail["unverified_gates"] = unverified
+    return second, detail

quantbom/actions/record_provenance.py

@@ -0,0 +1,49 @@
+"""record_provenance — build provenance and a manifest-digest record.
+
+The `signature.json` written here is an honest, labelled placeholder
+(`manifest-digest/unsigned`), not a cryptographic signature: real signing is
+the `sign` action (sign_evidence.py), verified by CRA-SIGN-01.
+"""
+from __future__ import annotations
+
+from .base import PRODUCED, ActionResult, Context
+
+ID = "record_provenance"
+
+
+def run(ctx: Context) -> ActionResult:
+    from .. import _collect as C
+
+    provenance = {
+        "predicateType": "https://slsa.dev/provenance/v1",
+        # the same builder identity the producer's signed statement declares (_sign.BUILDER_ID)
+        "builder": {"id": "secqdevops/quantbom-sdk", "version": {"quantbom": C.sdk_version()}},
+        "buildType": "https://secqdevops/build/qrisp-qiskit",
+        "subject": [
+            {"name": "quantum/circuit.qpy", "digest": {"sha256": C.sha256_bytes(ctx.state["circuit_qpy"]).split(":", 1)[1]}},
+            {"name": "quantum/transpiled.qpy",
+             "digest": {"sha256": C.sha256_bytes(ctx.state["transpiled_qpy"]).split(":", 1)[1]}},
+        ],
+        "metadata": {
+            "release_id": ctx.release_id,
+            "qrisp_version": ctx.qrisp_version,
+            "qiskit_version": ctx.qiskit_version,
+        },
+    }
+    ctx.evidence_dir.mkdir(parents=True, exist_ok=True)
+    C._write_json(ctx.evidence_dir / "provenance.json", provenance)
+    signature = {
+        "signature_type": "manifest-digest/unsigned",
+        "subject": ctx.release_id,
+        "manifest_sha256": C.sha256_bytes(C.canonical_json(provenance).encode("utf-8")),
+        "note": "placeholder: replace with sigstore/in-toto or Ed25519 signing",
+    }
+    C._write_json(ctx.evidence_dir / "signature.json", signature)
+
+    props = [
+        {"name": "secqdevops:provenance-ref", "value": "evidence/provenance.json"},
+        {"name": "secqdevops:signature-ref", "value": "evidence/signature.json"},
+        {"name": "secqdevops:provenance-artifact-ref", "value": "evidence/provenance.json"},
+        {"name": "secqdevops:signature-artifact-ref", "value": "evidence/signature.json"},
+    ]
+    return ActionResult(ID, PRODUCED, props)

quantbom/actions/verify_conversion.py

@@ -0,0 +1,53 @@
+"""verify_conversion — the framework-to-Qiskit translation is faithful (feeds QNT-06).
+
+The comparison itself runs in the SDK (`_fidelity`), where the native
+Cirq/Braket/PennyLane object is still in hand; this action records the report
+verbatim — including `unfaithful` — for the gate to judge.
+"""
+from __future__ import annotations
+
+import json
+
+from .base import NOT_APPLICABLE, PRODUCED, ActionResult, Context
+
+ID = "verify_conversion"
+
+
+def run(ctx: Context) -> ActionResult:
+    ctx.state["conversion_verdict"] = None
+    if not ctx.conversion_fidelity:
+        return ActionResult(ID, NOT_APPLICABLE,
+                            reason=f"no adapter-side translation for {ctx.source_format} input")
+    from .. import _collect as C
+
+    report = {**ctx.conversion_fidelity, "release_id": ctx.release_id}
+    verdict = str(report.get("verdict"))
+    raw = (json.dumps(report, indent=2, ensure_ascii=True) + "\n").encode("utf-8")
+    ctx.quantum_dir.mkdir(parents=True, exist_ok=True)
+    (ctx.quantum_dir / "conversion-fidelity.json").write_bytes(raw)
+    ctx.state["conversion_verdict"] = verdict
+
+    props = [
+        {"name": "secqdevops:conversion-fidelity-ref", "value": "quantum/conversion-fidelity.json"},
+        {"name": "secqdevops:conversion-fidelity-sha256", "value": C.sha256_bytes(raw)},
+        {"name": "secqdevops:conversion-fidelity-verdict", "value": verdict},
+        # which method decided (K3): dense, statevector, decision-diagram, a '+'-joined set, or none
+        {"name": "secqdevops:conversion-fidelity-method", "value": str(report.get("method") or "none")},
+    ]
+    if ctx.native_export:
+        # the native program itself, as the framework exported it and as QNT-06
+        # compared it: hash-bound, signed, and bound to the report's own digest
+        # of the same bytes (CRA-INTEG-01), so the fingerprint is of the program,
+        # not only of a report about it
+        text, fmt = ctx.native_export
+        ext = "qasm" if str(fmt).startswith("openqasm") else "json" if str(fmt).endswith("json") else "txt"
+        native_raw = str(text).encode("utf-8")
+        (ctx.quantum_dir / f"native-program.{ext}").write_bytes(native_raw)
+        props += [
+            {"name": "secqdevops:native-program-ref", "value": f"quantum/native-program.{ext}"},
+            {"name": "secqdevops:native-program-sha256", "value": C.sha256_bytes(native_raw)},
+            {"name": "secqdevops:native-program-format", "value": str(fmt)},
+        ]
+    # an inconclusive report says why, so QNT-06's N-A names the real reason
+    why = f"inconclusive: {report.get('reason')}" if verdict == "inconclusive" and report.get("reason") else None
+    return ActionResult(ID, PRODUCED, props, reason=why)