quantbom 0.6.0__py3-none-any.whl

quantbom/_drift.py

@@ -0,0 +1,333 @@
+"""The semantic drift sentinel (QUANTUM_INNOVATION_OPPORTUNITIES.md I4).
+
+Toolchains change under an unchanged program: a new SDK, a new transpiler, a
+new frontend exporter. The compiled artifact then differs, and the question
+that matters for compliance is not *whether* it differs but *what kind* of
+difference it is (QUANTUM_CHALLENGES_PLAN.md; the CRA reading in the
+7 Oct 2026 drift analysis):
+
+  none           the compiled circuit is the one recorded in the baseline
+  nondeterministic  a different realisation under the SAME toolchain as the
+                 baseline — the compiler itself is not deterministic (Qrisp's
+                 is not); same meaning, so benign, but worth knowing
+  structural     a different realisation with the same unitary — benign;
+                 document the toolchain, nothing else changes
+  observational  the unitaries differ by what no measurement observes
+                 (identical measurement statistics) — benign for the program's
+                 behaviour, worth knowing about
+  semantic       the compiled circuit no longer means what the source means —
+                 a potential substantial modification; fails
+  inconclusive   the checker could not decide — reported, never silently passed
+
+Every classification is machine-checked with mqt.qcec: the compiled circuit
+against the SOURCE (does it still mean what was written?) and, when a baseline
+exists, against the baseline's compiled circuit (did meaning change since it
+was recorded?). Structure is compared by gate counts and depth; bytes are not
+compared, because QPY serialisation changes between Qiskit versions without
+anything else changing.
+
+A corpus is a Python module exposing PROGRAMS: {name: (framework, builder)},
+the builder returning the framework's native object. The baseline is a JSON
+file recorded with `quantbom drift --update-baseline`; it stores each compiled
+circuit as OpenQASM 3 text so a later toolchain can load it.
+
+The baseline is recorded in CI on a PINNED toolchain (drift_corpus/toolchain.txt),
+never on a developer machine: `--require-pins` refuses to record when the
+installed versions differ from the pins, and the matrix's reference job runs
+`--strict` on those pins, where anything but `none` or `nondeterministic` means
+the baseline no longer matches the toolchain it claims to describe.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import sys
+from datetime import datetime, timezone
+from importlib.metadata import version as _version
+from pathlib import Path
+from typing import Any, Callable
+
+SCHEMA = "secqdevops.drift-baseline/v1"
+ORDER = ["none", "nondeterministic", "structural", "observational", "inconclusive", "semantic"]
+FAILS = {"semantic"}
+STRICT_OK = {"none", "nondeterministic", "skipped"}  # what a run ON the pinned toolchain may report
+
+
+def read_pins(path: str | Path) -> dict[str, str]:
+    """`dist==version` lines (requirements syntax); comments and blanks ignored."""
+    pins: dict[str, str] = {}
+    for line in Path(path).read_text(encoding="utf-8").splitlines():
+        line = line.split("#", 1)[0].strip()
+        if not line:
+            continue
+        if "==" not in line:
+            raise ValueError(f"pins must be exact (dist==version): {line!r}")
+        dist, ver = (x.strip() for x in line.split("==", 1))
+        pins[dist] = ver
+    return pins
+
+
+def pin_mismatches(pins: dict[str, str]) -> list[str]:
+    """Installed versions that differ from the pins (missing counts as a mismatch)."""
+    out = []
+    for dist, want in pins.items():
+        try:
+            have = _version(dist)
+        except Exception:
+            have = None
+        if have != want:
+            out.append(f"{dist}: pinned {want}, installed {have or 'not installed'}")
+    return out
+
+
+def strict_violations(report: dict[str, Any]) -> list[str]:
+    """Programs whose drift a pinned-toolchain run must not show."""
+    return [f"{n}: {e.get('drift')}" for n, e in report["programs"].items() if e.get("drift") not in STRICT_OK]
+
+
+def toolchain() -> dict[str, str]:
+    out: dict[str, str] = {}
+    for dist in ("qiskit", "qrisp", "cirq-core", "amazon-braket-sdk", "pennylane", "cudaq", "mqt.qcec", "qiskit-qasm3-import"):
+        try:
+            out[dist] = _version(dist)
+        except Exception:
+            pass
+    return out
+
+
+def fingerprint(qc) -> dict[str, Any]:
+    return {"ops": {k: int(v) for k, v in sorted(qc.count_ops().items())}, "depth": int(qc.depth()),
+            "size": int(qc.size()), "qubits": int(qc.num_qubits)}
+
+
+def qasm3_text(qc) -> str | None:
+    try:
+        from qiskit import qasm3
+
+        return qasm3.dumps(qc)
+    except Exception:
+        return None
+
+
+def qasm3_sha(qc) -> str | None:
+    text = qasm3_text(qc)
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest() if text is not None else None
+
+
+def load_qasm3(text: str):
+    from qiskit import qasm3
+
+    return qasm3.loads(text)
+
+
+def _final_measurements(circuit) -> bool:
+    from .actions.prove_equivalence import final_measurements
+
+    return final_measurements(circuit)
+
+
+def _dynamic(circuit) -> bool:
+    from ._circuit import inspect_circuit
+
+    return bool(inspect_circuit(circuit)["dynamic"])
+
+
+def meaning(source, compiled) -> tuple[str, dict[str, str]]:
+    """How `compiled` relates to `source`: unitary | dynamic | observational | semantic | inconclusive."""
+    from mqt import qcec
+
+    detail: dict[str, str] = {}
+    if _dynamic(source):
+        # the collector's own path for dynamic circuits (prove_equivalence.verify_dynamic)
+        from .actions.prove_equivalence import verify_dynamic
+
+        try:
+            result, dyn_detail = verify_dynamic(qcec, source, compiled)
+        except Exception as err:
+            return "inconclusive", {"error": f"{type(err).__name__}: {str(err)[:160]}"}
+        crit = str(result.equivalence).split(".")[-1]
+        detail["dynamic"] = crit
+        if result.considered_equivalent() and not (dyn_detail or {}).get("unverified_gates"):
+            return "dynamic", detail
+        return ("semantic" if crit == "not_equivalent" else "inconclusive"), detail
+    try:
+        full = qcec.verify(source, compiled)
+    except Exception as err:
+        return "inconclusive", {"error": f"{type(err).__name__}: {str(err)[:160]}"}
+    crit = str(full.equivalence).split(".")[-1]
+    detail["unitary"] = crit
+    if full.considered_equivalent():
+        return "unitary", detail
+    if crit != "not_equivalent":
+        return "inconclusive", detail
+    if _final_measurements(source):
+        from .actions.prove_equivalence import partial_check
+
+        try:
+            partial = partial_check(qcec, source, compiled)
+        except Exception as err:
+            detail["partial"] = f"error: {type(err).__name__}"
+            return "semantic", detail
+        detail["partial"] = str(partial.equivalence).split(".")[-1]
+        if partial.considered_equivalent():
+            return "observational", detail
+        if detail["partial"] != "not_equivalent":  # the partial check could not decide: no evidence either way
+            return "inconclusive", detail
+    return "semantic", detail
+
+
+def classify(source, compiled, baseline: dict[str, Any] | None, same_toolchain: bool = False) -> dict[str, Any]:
+    """One program's drift record. `baseline` is this program's entry from the baseline file, or None;
+    `same_toolchain` says whether the baseline was recorded with exactly this toolchain."""
+    kind, detail = meaning(source, compiled)
+    fp = fingerprint(compiled)
+    record: dict[str, Any] = {"compiled": fp, "vs_source": kind, "checks": detail, "vs_baseline": "n/a"}
+    if kind == "semantic":
+        drift = "semantic"
+    elif baseline is not None and baseline.get("compiled") == fp:
+        # the realisation is byte-identical to the baseline: no drift, whatever the
+        # meaning check managed this time (a timeout or an undecided QCEC check must
+        # not read as drift for an unchanged realisation)
+        drift, record["vs_baseline"] = "none", "unchanged"
+    elif kind == "inconclusive":
+        drift = "inconclusive"
+    elif baseline is None:
+        drift = "unbaselined"
+    else:
+        # the realisation changed since the baseline: did its meaning?
+        base_kind = "unknown"
+        if baseline.get("compiled_qasm3"):
+            try:
+                base_kind, base_detail = meaning(load_qasm3(baseline["compiled_qasm3"]), compiled)
+                record["checks"]["vs_baseline"] = base_detail
+            except Exception as err:
+                record["checks"]["vs_baseline"] = {"error": f"{type(err).__name__}: {str(err)[:160]}"}
+        record["vs_baseline"] = base_kind
+        if base_kind == "semantic":
+            drift = "semantic"
+        elif kind == "observational" or base_kind == "observational":
+            drift = "observational"
+        elif base_kind == "inconclusive" or base_kind == "unknown":
+            drift = "inconclusive"
+        elif same_toolchain:
+            drift = "nondeterministic"  # nothing changed but the compiler's own choices
+        else:
+            drift = "structural"
+    record["drift"] = drift
+    return record
+
+
+def load_corpus(path: str | Path) -> dict[str, tuple[str, Callable[[], Any]]]:
+    p = Path(path)
+    spec = importlib.util.spec_from_file_location(p.stem, p)
+    module = importlib.util.module_from_spec(spec)
+    sys.path.insert(0, str(p.parent))
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        sys.path.remove(str(p.parent))
+    programs = getattr(module, "PROGRAMS", None)
+    if not isinstance(programs, dict) or not programs:
+        raise ValueError(f"{p} must define PROGRAMS = {{name: (framework, builder)}}")
+    return programs
+
+
+def lower(obj):
+    """The program as the collector sees it: a Qiskit circuit, through the adapter."""
+    from qiskit import QuantumCircuit
+
+    if isinstance(obj, QuantumCircuit):
+        return obj
+    from .frameworks import detect
+
+    return detect(obj).lower(obj)[0]
+
+
+def compile_(source):
+    from qiskit import transpile
+
+    from . import _collect as C
+
+    return transpile(source, basis_gates=C.BASIS_GATES, optimization_level=2, seed_transpiler=C.SEED_TRANSPILER)
+
+
+def run(programs: dict[str, tuple[str, Callable[[], Any]]], baseline: dict[str, Any] | None) -> tuple[dict[str, Any], int]:
+    """Compile every program in THIS toolchain, classify, and return (report, exit_code).
+
+    exit 1 when any program drifted semantically; 0 otherwise (structural and
+    observational drift are reported, inconclusive and skipped programs too).
+    """
+    base_programs = (baseline or {}).get("programs", {})
+    report: dict[str, Any] = {"schema": "secqdevops.drift-report/v1",
+                              "run_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                              "toolchain": toolchain(),
+                              "baseline_toolchain": (baseline or {}).get("recorded_with"),
+                              "programs": {}}
+    for name, (framework, builder) in programs.items():
+        entry: dict[str, Any] = {"framework": framework}
+        try:
+            native = builder()
+        except ImportError as err:
+            entry.update(drift="skipped", reason=f"{framework} not installed ({err.name})")
+            report["programs"][name] = entry
+            continue
+        except Exception as err:  # the framework refused the program in this version — that is itself a finding
+            entry.update(drift="skipped", reason=f"program could not be built: {type(err).__name__}: {str(err)[:160]}")
+            report["programs"][name] = entry
+            continue
+        try:
+            source = lower(native)
+            compiled = compile_(source)
+        except Exception as err:
+            entry.update(drift="inconclusive", reason=f"could not lower/compile: {type(err).__name__}: {str(err)[:160]}")
+            report["programs"][name] = entry
+            continue
+        entry["source_qasm3_sha256"] = qasm3_sha(source)
+        base = base_programs.get(name)
+        if base and base.get("source_qasm3_sha256") not in (None, entry["source_qasm3_sha256"]):
+            entry["source_changed"] = True  # the program itself (or its exporter) changed since the baseline
+        entry.update(classify(source, compiled, base, same_toolchain=(report["toolchain"] == report["baseline_toolchain"])))
+        entry["compiled_qasm3"] = qasm3_text(compiled)
+        report["programs"][name] = entry
+    worst = max((e.get("drift") for e in report["programs"].values() if e.get("drift") in ORDER), key=ORDER.index, default="none")
+    report["summary"] = {
+        "worst": worst,
+        "counts": {k: sum(1 for e in report["programs"].values() if e.get("drift") == k)
+                   for k in ORDER + ["unbaselined", "skipped"]},
+        "nondeterministic_programs": sorted(n for n, e in report["programs"].items() if e.get("drift") == "nondeterministic"),
+    }
+    return report, (1 if worst in FAILS else 0)
+
+
+def baseline_from(report: dict[str, Any], pins_path: str | Path | None = None) -> dict[str, Any]:
+    """Record this run as the baseline later runs are compared with."""
+    import os
+
+    provenance = {k: os.environ[k] for k in ("GITHUB_REPOSITORY", "GITHUB_RUN_ID", "GITHUB_SHA", "GITHUB_WORKFLOW") if os.environ.get(k)}
+    return {
+        "schema": SCHEMA,
+        "recorded_at": report["run_at"],
+        "recorded_with": report["toolchain"],
+        "pins": str(pins_path) if pins_path else None,
+        "pins_sha256": ("sha256:" + hashlib.sha256(Path(pins_path).read_bytes()).hexdigest()) if pins_path else None,
+        "recorded_in": provenance or {"note": "recorded outside CI — provisional until re-recorded on the pinned toolchain"},
+        "programs": {name: {"framework": e["framework"], "source_qasm3_sha256": e.get("source_qasm3_sha256"),
+                            "compiled": e.get("compiled"), "vs_source": e.get("vs_source"),
+                            "compiled_qasm3": e.get("compiled_qasm3")}
+                     for name, e in report["programs"].items() if e.get("compiled")},
+    }
+
+
+def render(report: dict[str, Any]) -> str:
+    lines = [f"drift sentinel — toolchain {report['toolchain']}"]
+    if report.get("baseline_toolchain"):
+        lines.append(f"baseline recorded with {report['baseline_toolchain']}")
+    w = max((len(n) for n in report["programs"]), default=8)
+    for name, e in report["programs"].items():
+        d = e.get("drift", "?")
+        extra = e.get("reason") or (f"vs source: {e.get('vs_source')}; vs baseline: {e.get('vs_baseline')}" if "vs_source" in e else "")
+        lines.append(f"  {name:{w}}  {d:13} {extra}")
+    s = report["summary"]
+    lines.append(f"worst: {s['worst']}  {s['counts']}")
+    return "\n".join(lines)

quantbom/_fidelity.py

@@ -0,0 +1,280 @@
+"""QNT-06 — frontend conversion fidelity (client side).
+
+Every framework is lowered to one Qiskit circuit before evidence is collected,
+and QNT-05 then proves *that* circuit equivalent to its transpiled form. For
+Cirq, Braket and PennyLane there is an earlier step — native object ->
+OpenQASM -> Qiskit — that QNT-05 cannot see: if an adapter mistranslates a
+gate, QNT-05 faithfully certifies the wrong circuit.
+
+This module closes that step. It computes the circuit's unitary with the
+framework's OWN simulator (the authoritative reference for what the developer
+wrote) and compares it with the converted Qiskit circuit, up to global phase.
+
+Design rules, matching the rest of the scheme:
+  * Qubit order is pinned per framework, never "whichever matches". All three
+    put qubit 0 first (big-endian), Qiskit puts it last; a converter that
+    reversed the register would be a genuine mistranslation and must fail.
+  * Anything that cannot be decided — too many qubits for a dense unitary,
+    mid-circuit measurement, mismatched register size, an unexpected error —
+    is `inconclusive`, which the gate reports as N-A. Never affirmative,
+    never a blocker.
+  * Runs only where a translation exists. Qiskit inputs need none; Qrisp's
+    `.to_qiskit()` *is* Qrisp's compiler, whose intent is checked by
+    QBOM-BENCH-02 and re-execution rather than by unitary comparison.
+
+The native program never leaves the client, so the server cannot recompute
+this verdict. It is client-computed evidence, hash-bound (CRA-INTEG-01),
+signature-bound (CRA-SIGN-01) and consistency-checked against its declared
+verdict — the same trust model as QNT-05.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any
+
+from .frameworks import ADAPTERS, Undecidable
+from .frameworks import get as _adapter
+
+SCHEMA = "secqdevops.conversion-fidelity/v1"
+# Frameworks whose adapter performs a translation QNT-06 must check — derived
+# from the adapter registry, so a new adapter is covered without editing this.
+TRANSLATED_FRONTENDS = tuple(a.name for a in ADAPTERS if a.translates)
+TOLERANCE = 1e-7
+NON_UNITARY_OPS = {"measure", "reset", "delay", "initialize"}
+
+_Inconclusive = Undecidable  # former name, kept for callers
+
+
+# A dense 2^n x 2^n unitary: 10 qubits is 16 MiB of complex128, 12 is 256 MiB.
+# Declared per framework in harness_manifest.json (capabilities.max_reference_qubits)
+# and held to this constant by the contract check.
+DEFAULT_MAX_QUBITS = 10
+# A state vector is 2^n amplitudes: 20 qubits is 16 MiB. The scalable reference
+# beyond the dense cap (K3); declared as capabilities.max_statevector_qubits.
+DEFAULT_MAX_STATE_QUBITS = 20
+METHODS = ("dense", "statevector", "decision-diagram")
+
+
+def max_qubits() -> int:
+    return int(os.environ.get("QUANTBOM_FIDELITY_MAX_QUBITS", str(DEFAULT_MAX_QUBITS)))
+
+
+def max_state_qubits() -> int:
+    return int(os.environ.get("QUANTBOM_STATEVECTOR_MAX_QUBITS", str(DEFAULT_MAX_STATE_QUBITS)))
+
+
+def _strip_measurements(converted: Any):
+    qc = converted.remove_final_measurements(inplace=False)
+    remaining = NON_UNITARY_OPS & set(qc.count_ops())
+    if remaining:
+        raise _Inconclusive(f"converted circuit is not unitary ({', '.join(sorted(remaining))})")
+    return qc
+
+
+def _converted_unitary(converted: Any):
+    from qiskit.quantum_info import Operator
+
+    # Qiskit is little-endian; the native frameworks are big-endian (see module doc).
+    return Operator(_strip_measurements(converted)).reverse_qargs().data
+
+
+def _converted_state(converted: Any):
+    from qiskit.quantum_info import Statevector
+
+    return Statevector(_strip_measurements(converted)).reverse_qargs().data
+
+
+def _aligned_deviation(native, converted_arr, np) -> tuple[float, str | None]:
+    """Max |native - phase * converted| after aligning the global phase at the
+    native array's largest entry; a reason when no alignment is possible."""
+    if native.shape != converted_arr.shape:
+        raise _Inconclusive(f"register size differs: native {native.shape[0]} vs converted {converted_arr.shape[0]} "
+                            "basis states — not comparable like for like")
+    i = np.unravel_index(np.argmax(np.abs(native)), native.shape)
+    if abs(converted_arr[i]) < 1e-12:
+        return float(np.max(np.abs(native - converted_arr))), "the converted circuit has no amplitude where the native circuit's largest one is"
+    aligned = (native[i] / converted_arr[i]) * converted_arr
+    return float(np.max(np.abs(native - aligned))), None
+
+
+def _entry(name: str, description: str, reference: str | None = None, verdict: str = "inconclusive",
+           reason: str | None = None, deviation: float | None = None) -> dict[str, Any]:
+    return {"name": name, "description": description, "reference": reference, "verdict": verdict,
+            "reason": reason, "max_abs_deviation": deviation}
+
+
+def _dense(adapter, native, converted, np) -> dict[str, Any]:
+    desc = "unitary comparison up to global phase"
+    try:
+        native_u, reference = adapter.reference_unitary(native)
+        native_u = np.asarray(native_u, dtype=complex)
+        deviation, why = _aligned_deviation(native_u, _converted_unitary(converted), np)
+        if why:
+            return _entry("dense", desc, reference, "unfaithful", why, deviation)
+        if deviation <= TOLERANCE:
+            return _entry("dense", desc, reference, "faithful", None, deviation)
+        return _entry("dense", desc, reference, "unfaithful",
+                      "the converted circuit computes a different transformation from the native one", deviation)
+    except _Inconclusive as why:
+        return _entry("dense", desc, None, "inconclusive", str(why))
+    except Exception as err:
+        return _entry("dense", desc, None, "inconclusive", f"comparison failed: {type(err).__name__}: {err}")
+
+
+def _statevector(adapter, native, converted, np) -> dict[str, Any]:
+    desc = ("state-vector comparison on |0...0> up to global phase — the framework's own simulator, "
+            "but one input state: weaker than a unitary comparison")
+    try:
+        native_s, reference = adapter.reference_state(native)
+        native_s = np.asarray(native_s, dtype=complex).reshape(-1)
+        deviation, why = _aligned_deviation(native_s, _converted_state(converted), np)
+        if why:
+            return _entry("statevector", desc, reference, "unfaithful", why, deviation)
+        if deviation <= TOLERANCE:
+            return _entry("statevector", desc, reference, "faithful", None, deviation)
+        return _entry("statevector", desc, reference, "unfaithful",
+                      "the converted circuit maps |0...0> to a different state from the native one", deviation)
+    except _Inconclusive as why:
+        return _entry("statevector", desc, None, "inconclusive", str(why))
+    except Exception as err:
+        return _entry("statevector", desc, None, "inconclusive", f"comparison failed: {type(err).__name__}: {err}")
+
+
+def _decision_diagram(adapter, native, converted) -> dict[str, Any]:
+    desc = ("decision-diagram equivalence (mqt.qcec) of the hash-bound native export, parsed by mqt-core "
+            "independently of Qiskit's loader, against the converted circuit — reference = the exported "
+            "text, not the framework's simulator")
+    try:
+        import importlib
+
+        qcec = importlib.import_module("mqt.qcec")  # honours an absent/blocked module even when `mqt` is loaded
+    except ImportError:
+        return _entry("decision-diagram", desc, None, "inconclusive", "mqt.qcec is not installed (pip install 'quantbom[verify]')")
+    import tempfile
+    from pathlib import Path
+
+    try:
+        text, fmt, note = adapter.export_for_equivalence(native)
+        reference = f"native export ({fmt}) parsed by mqt-core" + (f"; {note}" if note else "")
+        with tempfile.TemporaryDirectory() as d:
+            path = Path(d) / f"native.{'qasm' if fmt.startswith('openqasm') else 'txt'}"
+            path.write_text(text, encoding="utf-8")
+            result = qcec.verify(str(path), converted)
+        criterion = str(result.equivalence).split(".")[-1]
+        if result.considered_equivalent():
+            return _entry("decision-diagram", desc, reference, "faithful")
+        if criterion == "not_equivalent":
+            return _entry("decision-diagram", desc, reference, "unfaithful",
+                          "the exported text and the converted circuit compute different transformations")
+        return _entry("decision-diagram", desc, reference, "inconclusive", f"mqt.qcec: {criterion}")
+    except Exception as err:
+        return _entry("decision-diagram", desc, None, "inconclusive", f"comparison failed: {type(err).__name__}: {str(err)[:160]}")
+
+
+def assess_conversion(native: Any, converted: Any, source_format: str) -> dict[str, Any] | None:
+    """Return a conversion-fidelity report, or None when no translation exists.
+
+    Methods, by size (K3): `dense` up to the dense cap; beyond it `statevector`
+    (the framework's own simulator, one input state) up to the state-vector cap
+    together with `decision-diagram` (the exported text through an independent
+    parser, full operator). When `dense` is within the cap but cannot decide
+    (K1: CUDA-Q drops idle qubits from its unitary; a framework without
+    `get_unitary`), the same two scalable methods are tried next — a verdict
+    then names the weaker reference it rests on. Any `unfaithful` method decides
+    `unfaithful`; else any `faithful` method decides `faithful` and `reference`
+    names which; else `inconclusive`. Every method's result is in the report.
+    Never raises.
+    """
+    if source_format not in TRANSLATED_FRONTENDS:
+        return None
+    import numpy as np
+
+    cap, scap = max_qubits(), max_state_qubits()
+    n = int(getattr(converted, "num_qubits", 0) or 0)
+    report: dict[str, Any] = {
+        "schema": SCHEMA,
+        "frontend": source_format,
+        "method": None,
+        "methods": [],
+        "qubit_order": "framework qubit 0 is most significant; compared against the bit-reversed Qiskit operator or state",
+        "tolerance": TOLERANCE,
+        "max_qubits": cap,
+        "max_statevector_qubits": scap,
+        "qubits": n,
+        "reference": None,
+        "max_abs_deviation": None,
+        "native_export_format": None,
+        "native_export_sha256": None,
+        "verdict": "inconclusive",
+        "reason": None,
+    }
+    try:
+        adapter = _adapter(source_format)
+        if adapter.reference != "dense":
+            raise _Inconclusive(f"the {source_format} adapter declares no dense reference ({adapter.reference!r}); "
+                                "no method is available to compare the translation")
+        text, fmt = adapter.native_export(native)
+        report["native_export_format"] = fmt
+        report["native_export_sha256"] = "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+        entries: list[dict[str, Any]] = []
+        if n <= cap:
+            entries.append(_dense(adapter, native, converted, np))
+        if n > cap or entries[-1]["verdict"] == "inconclusive":
+            if n <= scap:
+                entries.append(_statevector(adapter, native, converted, np))
+            else:
+                entries.append(_entry("statevector", "state-vector comparison", None, "inconclusive",
+                                      f"{n} qubits exceeds the state-vector cap of {scap} (QUANTBOM_STATEVECTOR_MAX_QUBITS)"))
+            entries.append(_decision_diagram(adapter, native, converted))
+        report["methods"] = entries
+        deviations = [e["max_abs_deviation"] for e in entries if e["max_abs_deviation"] is not None]
+        report["max_abs_deviation"] = max(deviations) if deviations else None
+        unfaithful = [e for e in entries if e["verdict"] == "unfaithful"]
+        faithful = [e for e in entries if e["verdict"] == "faithful"]
+        decisive = unfaithful or faithful
+        report["method"] = "+".join(e["name"] for e in decisive) if decisive else "none"
+        report["reference"] = "; ".join(f"{e['name']}: {e['reference']}" for e in decisive if e["reference"]) or None
+        if unfaithful:
+            report["verdict"] = "unfaithful"
+            report["reason"] = "; ".join(f"{e['name']}: {e['reason']}" for e in unfaithful)
+        elif faithful:
+            report["verdict"] = "faithful"
+        else:
+            report["reason"] = "; ".join(f"{e['name']}: {e['reason']}" for e in entries if e["reason"]) or "no method could decide"
+    except _Inconclusive as why:
+        report["reason"] = str(why)
+    except Exception as err:  # never block collection, never affirm
+        report["reason"] = f"comparison failed: {type(err).__name__}: {err}"
+    return report
+
+
+# ---- QNT-09: the native program on its own framework's simulator ----
+DEFAULT_NATIVE_SHOTS = 8192
+
+
+def native_shots() -> int:
+    return int(os.environ.get("QUANTBOM_NATIVE_SHOTS", str(DEFAULT_NATIVE_SHOTS)))
+
+
+def sample_native(native: Any, converted: Any, source_format: str) -> dict[str, Any] | None:
+    """Run the native program on its framework's own simulator (QNT-09).
+
+    None for inputs that are the shared format itself. Otherwise the adapter's
+    native_run() result with "framework" and "shots", or {"reason": ...} when
+    the framework could not run it or the program is beyond the state-vector cap
+    (every framework simulator here is exponential in qubits). Never raises.
+    """
+    if source_format not in TRANSLATED_FRONTENDS:
+        return None
+    n = int(getattr(converted, "num_qubits", 0) or 0)
+    if n > max_state_qubits():
+        return {"reason": f"{n} qubits exceeds the state-vector cap of {max_state_qubits()} (QUANTBOM_STATEVECTOR_MAX_QUBITS)"}
+    try:
+        shots = native_shots()
+        run = _adapter(source_format).native_run(native, shots)
+        return {**run, "framework": source_format, "shots": shots}
+    except Exception as err:  # Undecidable carries the adapter's own reason
+        why = str(err) if isinstance(err, _Inconclusive) else f"{type(err).__name__}: {err}"
+        return {"reason": why}