quantbom 0.6.0__py3-none-any.whl

quantbom/cli.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""QuantBOM CLI — certify a quantum release from your code, a file or the built-in demo.
+
+    export QUANTBOM_API_KEY=qb_live_...
+    quantbom certify --entry my_pkg.circuits:build --release my-app@1.0   # any supported framework
+    quantbom certify --qpy circuit.qpy --release my-app@1.0
+    quantbom certify --qasm3 program.qasm3 --release my-app@1.0
+    quantbom certify --demo --release smoke-test
+
+    # sign the evidence as its producer (the authorship claim CRA-SIGN-01 rests on)
+    quantbom keygen                                                       # once: ~/.quantbom/signing.key
+    quantbom certify --entry my_pkg.circuits:build --release my-app@1.0 --sign
+
+    # two-step, when partner evidence or a signature joins the bundle first
+    quantbom collect --entry my_pkg.circuits:build --release my-app@1.0 --out bundle/
+    python emit_test_evidence.py emit ... --inject-sbom bundle/sbom.cdx.json
+    quantbom attest tests --bundle bundle/ --suite quantum-security-suite --outcome passed --passed 42
+    quantbom attest vulns --bundle bundle/ --policy-url https://example.org/security --contact mailto:security@example.org
+    quantbom attest constant-time --bundle bundle/ --tool dudect --target kyber_decaps --measurements timings.csv
+    quantbom attest crypto --bundle bundle/ --cbom cbom.cdx.json
+    quantbom sign --bundle bundle/                 # last: the signature covers what the attests added
+    quantbom certify --bundle bundle/ --release my-app@1.0
+
+    # an auditor, offline: re-derive digests, signatures and bindings; the service key must be anchored
+    quantbom keys --pin                       # fetch https://certify.zortenet.eu/v1/keys once, pin it
+    quantbom verify .quantbom/my-app@1.0       # or a zip of the mirror; exit 0 only on VERIFIED
+
+    # what can the harness do for my framework / for this requirement?
+    quantbom actions --framework cirq
+    quantbom actions --requirement CRA-II-3
+
+    # did a toolchain change alter what my programs mean? (semantic drift sentinel)
+    quantbom drift --corpus drift_corpus/programs.py              # exit 1 on semantic drift
+    quantbom drift --corpus drift_corpus/programs.py --update-baseline
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import STRICT_WITHHELD_REFS, certify, collect
+
+
+def _add_source(p: argparse.ArgumentParser, *, bundle: bool) -> None:
+    src = p.add_mutually_exclusive_group(required=True)
+    src.add_argument("--entry", metavar="MODULE:ATTR",
+                     help="circuit object from your code (module:attr or file.py:attr; a function is called) — "
+                          "Qiskit, Qrisp, Cirq, Braket, PennyLane or CUDA-Q")
+    src.add_argument("--qpy", help="Qiskit-native circuit (QPY file)")
+    src.add_argument("--qasm3", help="OpenQASM3 file")
+    src.add_argument("--demo", action="store_true", help="use the built-in Qrisp demo circuit")
+    if bundle:
+        src.add_argument("--bundle", metavar="DIR", help="certify a bundle made by `quantbom collect` (nothing is re-collected)")
+
+
+def _add_collection(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--release", required=True)
+    p.add_argument("--backend", default="basic", choices=["basic", "generic", "ibm"],
+                   help="basic: local ideal simulator · generic: synthetic seeded device (GenericBackendV2; "
+                        "noise with quantbom[sim]) · ibm: real hardware (credentials needed)")
+    p.add_argument("--environment", "-E", action="store_true",
+                   help="merge a syft scan of the running Python environment into the QBOM (needs syft on PATH)")
+    p.add_argument("--syft-sbom", help="merge a pre-generated CycloneDX environment SBOM (syft/trivy/cdxgen JSON)")
+    p.add_argument("--vuln-scan", "-V", action="store_true",
+                   help="run grype over the QBOM so CRA-ESR-03 and the VEX carry real findings (needs grype on PATH)")
+    p.add_argument("--grype-output", help="apply a pre-generated grype CycloneDX JSON instead of running grype")
+    p.add_argument("--equivalence", "-Q", action="store_true",
+                   help="formally verify source-vs-transpiled equivalence (needs mqt.qcec: pip install 'quantbom[verify]')")
+    p.add_argument("--expect", action="append", metavar="OUTCOME=PROB",
+                   help="declare an expected outcome probability (repeatable), e.g. --expect 00101011010=1.0")
+    p.add_argument("--tolerance", type=float, default=0.05,
+                   help="max total-variation distance for --expect (default 0.05)")
+    p.add_argument("--expected-order", default="native", choices=["native", "qiskit"],
+                   help="bit order of --expect outcomes: your framework's own (default) or Qiskit's measured order")
+
+
+def _source_kwargs(args) -> dict:
+    if args.entry:
+        from .harness import resolve_entry
+
+        return {"circuit": resolve_entry(args.entry)}
+    if args.qpy:
+        return {"qpy": args.qpy}
+    if args.qasm3:
+        return {"qasm3": args.qasm3}
+    if getattr(args, "bundle", None):
+        return {"bundle": args.bundle}
+    from . import _collect as qe
+
+    return {"circuit": qe.build_demo_circuit().to_qiskit()}
+
+
+def _collection_kwargs(args) -> dict:
+    return dict(backend=args.backend, environment=args.environment, syft_sbom=args.syft_sbom,
+                vuln_scan=args.vuln_scan, grype_output=args.grype_output, equivalence=args.equivalence,
+                expected={k: float(v) for k, v in (e.split("=", 1) for e in args.expect)} if args.expect else None,
+                tolerance=args.tolerance, expected_order=args.expected_order)
+
+
+def _print_actions(result: dict, framework: str | None) -> None:
+    mark = {"supported": "yes", "not_applicable": "n/a", "unsupported": "NO", "external": "external"}
+    for a in result["actions"]:
+        line = f"{a['id']:<30} {a['provider']:<5}"
+        if framework:
+            st = a["status"]
+            word = mark.get(st.get("status"), "?")
+            if st.get("conformance") == "pending" and word == "yes":
+                word = "yes?"  # the adapter supports it; the conformance suite has not run on this framework
+            line += f" {word:<9}"
+        line += f" {'opt-in' if a.get('opt_in') else 'always':<7} {', '.join(a['controls']) or '—'}"
+        print(line)
+        if framework and a["status"].get("reason"):
+            print(f"{'':<32}why: {a['status']['reason']}")
+        reqs = "; ".join(f"{s}: {', '.join(ids)}" for s, ids in a["requirements"].items())
+        if reqs:
+            print(f"{'':<32}serves {reqs}")
+        how = a.get("how") or {}
+        for key in ("cli", "sdk", "install"):
+            if how.get(key):
+                print(f"{'':<32}{key}: {how[key]}")
+        for cmd in how.get("commands", []):
+            print(f"{'':<32}run: {cmd}")
+        if how.get("commands") and not how.get("cli"):
+            print(f"{'':<32}     (MOD-08 repository tool — not part of the quantbom wheel)")
+        elif how.get("commands"):
+            print(f"{'':<32}     (the same evidence, from the repository script)")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="quantbom", description="QuantBOM — certify a quantum release")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("certify", help="collect evidence (or take a collected bundle) and certify a release")
+    _add_source(c, bundle=True)
+    _add_collection(c)
+    c.add_argument("--mode", default="report", choices=["report", "gate"])
+    c.add_argument("--privacy", default="standard", choices=["standard", "strict"],
+                   help="strict: circuit-IR bytes (QPY/OpenQASM) never leave this machine; digests are client-attested")
+    c.add_argument("--assurance", default="standard", choices=["standard", "re-executed"],
+                   help="re-executed: the service independently re-runs the circuit and must reproduce the claimed results (extra credit)")
+    c.add_argument("--scheme", default="eu-cra",
+                   help="compliance scheme to certify under (default eu-cra; see GET /v1/schemes)")
+    c.add_argument("--retain", action="store_true",
+                   help="opt into server-side retention of the QBOM document + results (never artifact bytes); manage via /v1/releases")
+    c.add_argument("--sign", action="store_true",
+                   help="sign the evidence as its producer before upload (quantbom keygen first; needs quantbom[signing])")
+    c.add_argument("--key", metavar="FILE", help="producer signing key for --sign (default $QUANTBOM_SIGNING_KEY, then ~/.quantbom/signing.key)")
+    c.add_argument("--api-url")
+    c.add_argument("--api-key")
+
+    g = sub.add_parser("keygen", help="generate your producer signing key (Ed25519; private key written 0600)")
+    g.add_argument("--key-dir", metavar="DIR", help="where to write signing.key and signing.pub (default ~/.quantbom)")
+    g.add_argument("--force", action="store_true", help="replace an existing key (certificates already issued name the old key id)")
+
+    s_ = sub.add_parser("sign", help="sign a collected bundle as its producer (evidence/attestation.json + signing properties)")
+    s_.add_argument("--bundle", required=True, metavar="DIR", help="bundle from `quantbom collect`")
+    s_.add_argument("--key", metavar="FILE", help="producer signing key (default $QUANTBOM_SIGNING_KEY, then ~/.quantbom/signing.key)")
+    s_.add_argument("--strict", action="store_true",
+                    help="the bundle will be uploaded with --privacy strict: leave the withheld circuit files out of the signature")
+
+    k = sub.add_parser("collect", help="collect the evidence bundle locally, without contacting the service")
+    _add_source(k, bundle=False)
+    _add_collection(k)
+    k.add_argument("--out", required=True, metavar="DIR", help="directory to write the bundle to")
+
+    v = sub.add_parser("verify", help="verify a certified release offline: digests, signatures and bindings re-derived from bytes "
+                                      "(the gate's controls are not re-run; that needs the gate)")
+    v.add_argument("path", help="the mirror directory (.quantbom/<release>/), a `quantbom collect` bundle, or a zip of either")
+    v.add_argument("--certificate", metavar="FILE", help="certificate.json, when not beside the QBOM")
+    anchor = v.add_mutually_exclusive_group()
+    anchor.add_argument("--keys", metavar="FILE", help="a /v1/keys document to trust (default: the one pinned by `quantbom keys --pin`)")
+    anchor.add_argument("--service-key", metavar="FILE", help="a single service public key (PEM) to trust")
+    v.add_argument("--json", action="store_true", help="print the full report as JSON")
+
+    at = sub.add_parser("attest", help="add partner / tool evidence to a collected bundle (MOD-05 tests, MOD-07 VEX + CVD policy, "
+                                       "MOD-09 constant-time proof, MOD-03/09 CBOM agility) — before `quantbom sign`")
+    ats = at.add_subparsers(dest="attest", required=True)
+    t_ = ats.add_parser("tests", help="MOD-05 security test report (control MOD05-TEST-01)")
+    t_.add_argument("--bundle", required=True, metavar="DIR")
+    t_.add_argument("--suite", required=True)
+    t_.add_argument("--outcome", required=True, choices=["passed", "failed"])
+    t_.add_argument("--passed", type=int, default=0)
+    t_.add_argument("--failed", type=int, default=0)
+    t_.add_argument("--skipped", type=int, default=0)
+    t_.add_argument("--tool", default="mod05", help="the test tool and version")
+    t_.add_argument("--source-module", default="MOD-05")
+    vu = ats.add_parser("vulns", help="VEX/VDR over the release plus a CVD-policy attestation (CRA-VULN-01, CRA-VDP-01)")
+    vu.add_argument("--bundle", required=True, metavar="DIR")
+    vu.add_argument("--policy-url", required=True, help="public coordinated-disclosure policy URL")
+    vu.add_argument("--contact", required=True, help="security contact (mailto: or URL)")
+    vu.add_argument("--sla-days", type=int, default=90)
+    vu.add_argument("--advisories", metavar="FILE", help='MOD-07 advisories ({"vulnerabilities": [...]}) merged into the release before the VEX is built')
+    ct = ats.add_parser("constant-time", help="constant-time proof from a dudect / ctgrind / Binsec-Rel result (CRA-ESR-06)")
+    ct.add_argument("--bundle", required=True, metavar="DIR")
+    ct.add_argument("--tool", required=True, choices=["binsec-rel", "ctgrind", "dudect"])
+    ct.add_argument("--target", required=True, help="analysed component (purl or symbol)")
+    src = ct.add_mutually_exclusive_group(required=True)
+    src.add_argument("--t-value", type=float, help="precomputed Welch t-statistic / tool t-value")
+    src.add_argument("--measurements", metavar="CSV", help="two-column CSV: class,nanoseconds (Welch's t is computed here)")
+    ct.add_argument("--threshold", type=float, default=10.0, help="|t| above this is leakage (dudect's 10)")
+    cr = ats.add_parser("crypto", help="CBOM ingestion and PQC migration readiness (CRA-CRYPTO-01)")
+    cr.add_argument("--bundle", required=True, metavar="DIR")
+    cr.add_argument("--cbom", metavar="FILE", help="CycloneDX CBOM; copied to crypto/cbom.cdx.json in the bundle (default: already there)")
+
+    ks = sub.add_parser("keys", help="show, or with --pin fetch, the service's certificate-signing keys (the trust anchor for `verify`)")
+    ks.add_argument("--pin", action="store_true", help="fetch /v1/keys from the service and pin it to ~/.quantbom/service-keys.json")
+    ks.add_argument("--api-url", help="service base URL (default $QUANTBOM_API_URL)")
+    ks.add_argument("--out", metavar="FILE", help="pin to this file instead")
+
+    a = sub.add_parser("actions", help="list harness actions: per framework, or those covering a requirement or control")
+    a.add_argument("--framework", help="qiskit, qrisp, cirq, braket, pennylane, cudaq — adds each action's status for it")
+    a.add_argument("--requirement", help="only actions whose evidence feeds this requirement (any scheme)")
+    a.add_argument("--control", help="only actions whose evidence feeds this control")
+    a.add_argument("--json", action="store_true", help="machine-readable output (same shape as GET /v1/harness)")
+
+    d = sub.add_parser("drift", help="semantic drift sentinel: compile a corpus in this toolchain and classify every change "
+                                     "(none / structural / observational / semantic) against the source and the baseline")
+    d.add_argument("--corpus", required=True, metavar="MODULE.py", help="a Python file defining PROGRAMS = {name: (framework, builder)}")
+    d.add_argument("--baseline", metavar="FILE", help="baseline JSON (default: <corpus>.baseline.json beside the corpus)")
+    d.add_argument("--update-baseline", action="store_true", help="record this run as the baseline (after reviewing the drift it reports)")
+    d.add_argument("--json", action="store_true", help="print the full report as JSON")
+    d.add_argument("--report", metavar="FILE", help="also write the report JSON here")
+    d.add_argument("--require-pins", metavar="FILE", help="refuse to run unless the installed toolchain equals these dist==version pins "
+                                                           "(how a baseline is only ever recorded on the pinned toolchain)")
+    d.add_argument("--strict", action="store_true", help="on the pinned toolchain: fail on anything but none / nondeterministic "
+                                                         "(the baseline no longer describes the toolchain it claims to)")
+    args = parser.parse_args()
+
+    if args.cmd in ("keygen", "sign"):
+        from . import _sign
+
+        try:
+            if args.cmd == "keygen":
+                out = _sign.keygen(args.key_dir, overwrite=args.force)
+            else:
+                out = _sign.sign(args.bundle, args.key, omit_refs=STRICT_WITHHELD_REFS if args.strict else ())
+        except (_sign.SigningUnavailable, FileNotFoundError, FileExistsError, ValueError) as err:
+            print(f"quantbom {args.cmd}: {err}", file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps(out, indent=2))
+        sys.exit(0)
+
+    if args.cmd == "attest":
+        from . import attest
+
+        try:
+            if args.attest == "tests":
+                out = attest.tests(args.bundle, suite=args.suite, outcome=args.outcome, passed=args.passed, failed=args.failed,
+                                   skipped=args.skipped, tool=args.tool, source_module=args.source_module)
+            elif args.attest == "vulns":
+                out = attest.vulnerability_handling(args.bundle, policy_url=args.policy_url, contact=args.contact,
+                                                    sla_days=args.sla_days, advisories=args.advisories)
+            elif args.attest == "constant-time":
+                out = attest.constant_time(args.bundle, tool=args.tool, target=args.target, t_value=args.t_value,
+                                           measurements=args.measurements, threshold=args.threshold)
+            else:
+                out = attest.crypto(args.bundle, cbom=args.cbom)
+        except (FileNotFoundError, ValueError, OSError) as err:
+            print(f"quantbom attest {args.attest}: {err}", file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps(out, indent=2))
+        sys.exit(0)
+
+    if args.cmd == "verify":
+        from . import _verify
+
+        try:
+            report = _verify.verify(args.path, certificate=args.certificate, keys_file=args.keys, service_key=args.service_key)
+        except (_verify.SigningUnavailable, FileNotFoundError, ValueError) as err:
+            print(f"quantbom verify: {err}", file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps(report, indent=2) if args.json else _verify.render(report))
+        sys.exit(0 if report["verdict"] == "VERIFIED" else 1)
+
+    if args.cmd == "keys":
+        from . import _verify
+
+        try:
+            if args.pin:
+                from . import _config
+
+                out = _verify.pin_keys(args.api_url or _config["api_url"], args.out)
+            else:
+                path = Path(args.out) if args.out else _verify.PINNED_KEYS
+                if not path.is_file():
+                    print(f"quantbom keys: nothing pinned at {path} — run `quantbom keys --pin`", file=sys.stderr)
+                    sys.exit(2)
+                out = json.loads(path.read_text())
+        except (_verify.SigningUnavailable, ValueError, OSError) as err:
+            print(f"quantbom keys: {err}", file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps(out, indent=2))
+        sys.exit(0)
+
+    if args.cmd == "drift":
+        from . import _drift
+
+        corpus = Path(args.corpus)
+        baseline_path = Path(args.baseline) if args.baseline else corpus.with_name(corpus.stem + ".baseline.json")
+        baseline = json.loads(baseline_path.read_text()) if baseline_path.exists() else None
+        try:
+            programs = _drift.load_corpus(corpus)
+        except (OSError, ValueError) as err:
+            print(f"quantbom drift: {err}", file=sys.stderr)
+            sys.exit(2)
+        if args.require_pins:
+            try:
+                mismatches = _drift.pin_mismatches(_drift.read_pins(args.require_pins))
+            except (OSError, ValueError) as err:
+                print(f"quantbom drift: {err}", file=sys.stderr)
+                sys.exit(2)
+            if mismatches:
+                print("quantbom drift: the installed toolchain is not the pinned one:\n  " + "\n  ".join(mismatches), file=sys.stderr)
+                sys.exit(2)
+        report, code = _drift.run(programs, baseline)
+        if args.strict:
+            bad = _drift.strict_violations(report)
+            if bad:
+                print("quantbom drift --strict: the baseline does not match this toolchain:\n  " + "\n  ".join(bad), file=sys.stderr)
+                code = 1
+        if args.report:
+            Path(args.report).write_text(json.dumps(report, indent=2))
+        if args.update_baseline:
+            baseline_path.write_text(json.dumps(_drift.baseline_from(report, args.require_pins), indent=2) + "\n")
+            print(f"baseline written: {baseline_path}", file=sys.stderr)
+        print(json.dumps(report, indent=2) if args.json else _drift.render(report))
+        if baseline is None and not args.update_baseline:
+            print("note: no baseline — drift vs baseline not assessed (run with --update-baseline to record one)", file=sys.stderr)
+        sys.exit(code)
+
+    if args.cmd == "actions":
+        from .harness import load_index, query
+
+        try:
+            result = query(load_index(), framework=args.framework, requirement=args.requirement, control=args.control)
+        except KeyError as err:
+            print(f"quantbom actions: {err.args[0]}", file=sys.stderr)
+            sys.exit(2)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(f"harness {result['harness_version']}" + (f" — {json.dumps(result['query'])}" if result["query"] else ""))
+            record = args.framework and load_index()["frameworks"][args.framework].get("conformance")
+            if isinstance(record, dict):
+                if record.get("status") == "verified":
+                    print(f"note: {args.framework} conformance verified — {record.get('versions')} · {record.get('host')} · {record.get('date')}")
+                else:
+                    print(f"note: {args.framework} conformance PENDING — {record.get('note', '')}; "
+                          "every 'yes' below is unverified until the suite has run")
+            elif record:
+                print(f"note: {args.framework} conformance {record}")
+            _print_actions(result, args.framework)
+        sys.exit(0)
+
+    if args.cmd == "collect":
+        try:
+            sbom = collect(release=args.release, out_dir=args.out, **_source_kwargs(args), **_collection_kwargs(args))
+        except ValueError as err:  # a refused input (e.g. unbound parameters): say why, no traceback
+            print(f"quantbom collect: {err}", file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps({"release_id": args.release, "bundle": str(sbom.parent), "qbom": str(sbom)}, indent=2))
+        sys.exit(0)
+
+    kw = dict(release=args.release, mode=args.mode, api_url=args.api_url, api_key=args.api_key,
+              privacy=args.privacy, retain=args.retain, assurance=args.assurance, scheme=args.scheme,
+              sign=args.sign, signing_key=args.key, **_collection_kwargs(args))
+    res = certify(**_source_kwargs(args), **kw)
+
+    keys = ("release_id", "overall_status", "assurance", "reexecution", "certificate", "verification", "credits_remaining", "retained", "mirror", "ok", "error")
+    print(json.dumps({k: res.get(k) for k in keys if k in res}, indent=2))
+    ok = res.get("ok") and (args.mode != "gate" or res.get("overall_status") == "COMPLIANT")
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

quantbom/frameworks/__init__.py

@@ -0,0 +1,67 @@
+"""Framework adapter registry (HARNESS_PLAN.md §2.1).
+
+Order matters for detection: Qiskit's isinstance check first, then Qrisp's
+duck-typed `.to_qiskit()`, then frameworks recognised by their module.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .base import FrameworkAdapter, Undecidable
+from .braket import BraketAdapter
+from .cirq import CirqAdapter
+from .cudaq import CudaqAdapter
+from .pennylane import PennyLaneAdapter
+from .qiskit import QiskitAdapter
+from .qrisp import QrispAdapter
+
+ADAPTERS: tuple[FrameworkAdapter, ...] = (
+    QiskitAdapter(), QrispAdapter(), CirqAdapter(), BraketAdapter(), PennyLaneAdapter(), CudaqAdapter(),
+)
+_BY_NAME = {a.name: a for a in ADAPTERS}
+
+
+def get(name: str) -> FrameworkAdapter | None:
+    return _BY_NAME.get(name)
+
+
+# K7: computational models the harness does not certify, recognised by the
+# module an object comes from, so the refusal names the model rather than
+# listing what was expected. The gate (22 controls, QBOM v0.3) is defined for
+# gate-model circuits; these need their own evidence model, not a translation.
+NON_GATE_MODELS = {
+    "annealing (Ising / QUBO)": ("dimod", "dwave", "dwavebinarycsp", "neal", "dwave_networkx", "qubovert", "pyqubo"),
+    "photonic (continuous-variable / linear optics)": ("strawberryfields", "perceval", "piquasso", "thewalrus"),
+    "analog / pulse-level": ("qutip", "pulser", "bloqade", "qiskit_dynamics", "qiskit.pulse"),
+    "annealing-style schedule (Braket AHS)": ("braket.ahs",),
+}
+GATE_MODEL_INPUTS = ("qiskit.QuantumCircuit, a Qrisp circuit/session (.to_qiskit()), a cirq.Circuit, "
+                     "a braket Circuit, a PennyLane QNode/tape, or a CUDA-Q kernel")
+
+
+def model_of(obj: Any) -> str | None:
+    """The non-gate model an object belongs to, by its type's module; None when unknown."""
+    module = type(obj).__module__ or ""
+    for model, roots in NON_GATE_MODELS.items():
+        if any(module == r or module.startswith(r + ".") for r in roots):
+            return model
+    return None
+
+
+def detect(obj: Any) -> FrameworkAdapter:
+    for adapter in ADAPTERS:
+        if adapter.detect(obj):
+            return adapter
+    model = model_of(obj)
+    if model:
+        raise TypeError(
+            f"{type(obj).__module__}.{type(obj).__name__} is an {model} program. QuantBOM certifies gate-model circuits "
+            f"({GATE_MODEL_INPUTS}): the 22 controls and the QBOM profile are defined for gates, measurements and "
+            "transpilation, so this program cannot be translated into that evidence; it is refused, not approximated"
+        )
+    raise TypeError(
+        f"certify() expects a gate-model circuit — {GATE_MODEL_INPUTS} — got {type(obj).__module__}.{type(obj).__name__}"
+    )
+
+
+__all__ = ["ADAPTERS", "FrameworkAdapter", "NON_GATE_MODELS", "Undecidable", "detect", "get", "model_of"]

quantbom/frameworks/base.py

@@ -0,0 +1,155 @@
+"""Framework adapter contract (HARNESS_PLAN.md §2.1).
+
+One adapter per quantum programming framework. Everything framework-specific
+in MOD-08 lives behind this interface: lowering to the normalized IR, the
+reference simulator QNT-06 compares against, the qubit/bit order, and the
+component the framework contributes to the inventory. Adding a framework means
+writing one adapter and passing tests/frameworks/test_conformance.py — nothing
+else in MOD-08 changes.
+
+Import rule: adapter modules import only the standard library at load time and
+pull their framework in lazily, inside methods. The harness contract check
+reads adapter facts on a bare Python with no quantum packages installed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class Undecidable(Exception):
+    """A comparison that cannot be decided — reported as `inconclusive` (N-A)."""
+
+
+def dist_version(dist: str) -> str:
+    try:
+        from importlib.metadata import version
+
+        return version(dist)
+    except Exception:
+        return "unknown"
+
+
+def qiskit_version() -> str:
+    from qiskit import __version__
+
+    return __version__
+
+
+class FrameworkAdapter:
+    #: source-format value recorded in the QBOM, and the manifest key
+    name: str = ""
+    #: PyPI distribution recorded as the framework's SBOM component
+    component: str = ""
+    #: SPDX licence of that component
+    license: str = ""
+    #: "qubit0_first": qubit 0 is the leftmost character of the framework's own
+    #: bitstrings; "qubit0_last": the rightmost (Qiskit's measured order);
+    #: "by-input": the reading differs by input kind — see `bit_orders`
+    bit_order: str = "qubit0_last"
+    #: input kind -> bit order, for a framework whose own readings differ by
+    #: input (Qrisp: QuantumCircuit.run() vs QuantumVariable.get_measurement()).
+    #: None when `bit_order` applies to every input.
+    bit_orders: dict[str, str] | None = None
+    #: None (input already is the IR), "qrisp-compiler" (the framework's own
+    #: compiler lowers it), or the OpenQASM dialect an adapter translates through
+    translation: str | None = None
+    #: True when the framework's dynamic constructs (mid-circuit measurement,
+    #: classical control) survive lowering and are conformance-tested (C7).
+    #: Enforced at collection: a dynamic program from an adapter that does not
+    #: claim it is refused, never certified on an unverified lowering.
+    supports_dynamic: bool = False
+    #: What QNT-06 compares the lowered circuit against: "dense" (the
+    #: framework's own simulator yields a dense unitary, capped by
+    #: _fidelity.max_qubits()), "stabilizer" (planned, K3) or "none" (no
+    #: adapter-side translation to check, or no reference available)
+    reference: str = "none"
+
+    @property
+    def translates(self) -> bool:
+        """True when an adapter-side translation exists that QNT-06 must check."""
+        return self.translation not in (None, "qrisp-compiler")
+
+    def detect(self, obj: Any) -> bool:
+        raise NotImplementedError
+
+    # ---- conventions, pinned per input (never "whichever matches") ----
+    def input_kind(self, obj: Any) -> str | None:
+        """The kind of input this object is, for frameworks with `bit_orders`."""
+        return None
+
+    def bit_order_for(self, obj: Any) -> str:
+        """How the framework's OWN reading of this object's outcomes is ordered."""
+        if self.bit_orders:
+            kind = self.input_kind(obj)
+            if kind not in self.bit_orders:
+                raise Undecidable(f"{self.name}: no declared bit order for input kind {kind!r}")
+            return self.bit_orders[kind]
+        return self.bit_order
+
+    def measured_order_for(self, obj: Any) -> str:
+        """How the LOWERED circuit's measured string is ordered: Qiskit's
+        (`qubit0_last`) unless the lowering allocates classical bits in reverse."""
+        return "qubit0_last"
+
+    def open_parameters(self, obj: Any) -> list[str]:
+        """Names of parameters the object leaves unbound — checked BEFORE lowering,
+        so an open circuit is refused with one clear message rather than whatever
+        the framework's exporter raises. Default: none known at this level (the
+        lowered Qiskit circuit is checked again in any case)."""
+        return []
+
+    def dynamic_features(self, obj: Any) -> list[str]:
+        """Dynamic constructs visible BEFORE lowering (mid-circuit measurement,
+        classical control), so an adapter that does not support them refuses
+        with one message instead of a library error. Default: none known at
+        this level; the lowered circuit is inspected again in any case."""
+        return []
+
+    def lower(self, obj: Any) -> tuple[Any, str, Any]:
+        """(qiskit_circuit, frontend_label, native_object_kept_for_evidence_or_None)."""
+        raise NotImplementedError
+
+    # ---- QNT-06 hooks — required only when `translates` ----
+    def native_export(self, obj: Any) -> tuple[str, str]:
+        """The exact text the translation consumed, and its format."""
+        raise Undecidable(f"no native export for {self.name}")
+
+    def reference_unitary(self, obj: Any) -> tuple[Any, str]:
+        """(unitary from the framework's OWN simulator, reference description)."""
+        raise Undecidable(f"no reference simulator for {self.name}")
+
+    def reference_state(self, obj: Any) -> tuple[Any, str]:
+        """(final state on |0...0> from the framework's OWN simulator, description) —
+        the scalable reference beyond the dense cap (K3); qubit 0 most significant."""
+        raise Undecidable(f"no reference state simulator for {self.name}")
+
+    def export_for_equivalence(self, obj: Any) -> tuple[str, str, str | None]:
+        """(text, format, note): the native export as an independent equivalence
+        checker can parse it. Default: the native export itself; an adapter whose
+        export uses non-standard gate names rewrites them and says so."""
+        text, fmt = self.native_export(obj)
+        return text, fmt, None
+
+    # ---- conformance hook: the framework's own reading of measurements ----
+    def native_sample(self, obj: Any, shots: int = 8) -> dict[str, int]:
+        raise NotImplementedError(f"{self.name} adapter has no native sampler")
+
+    # ---- QNT-09 hook: the program run on the framework's own simulator ----
+    def native_run(self, obj: Any, shots: int) -> dict[str, Any]:
+        """Sample the NATIVE program on the framework's own simulator.
+
+        Returns {"simulator": description, "reading": counts as the framework
+        reads them, "reading_order": "qubit0_first" | "measured",
+        "measured": the same counts keyed as the shared-format run's measured
+        string (spaces removed)}; Qrisp sessions add "by_variable". A program
+        without measurements is measured on every qubit, as the collector
+        measures the lowered circuit. Undecidable when the framework cannot
+        say, or the reading cannot be mapped onto the measured string."""
+        raise Undecidable(f"no native simulator run for {self.name}")
+
+    @staticmethod
+    def _reversed_reading(reading: dict[str, int], simulator: str) -> dict[str, Any]:
+        """For frameworks that print qubit 0 first: the measured string is the
+        reading reversed (registers concatenated in declaration order)."""
+        return {"simulator": simulator, "reading": reading, "reading_order": "qubit0_first",
+                "measured": {k[::-1]: int(v) for k, v in reading.items()}}