shotgate 0.2.2__tar.gz → 0.3.0__tar.gz

{shotgate-0.2.2 → shotgate-0.3.0}/.github/workflows/ci.yml

@@ -22,8 +22,8 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lint-and-core-tests:
-    name: lint + core tests
+  lint:
+    name: lint + types
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -34,22 +34,47 @@ jobs:
             docker.io/library/python:3.12-slim \
             public.ecr.aws/docker/library/python:3.12-slim
 
-      - name: ruff + mypy + core unit tests (containerized)
+      - name: ruff + mypy (containerized)
         run: |
           podman run --rm -v "$PWD:/work:Z" -w /work \
             docker.io/library/python:3.12-slim bash -euc "
               pip install -q -e '.[dev]'
               ruff check src tests
               mypy
-              pytest -q -m 'not integration' --junitxml=core-junit.xml
+            "
+
+  core-tests:
+    name: core unit tests (py ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    # The validation core is SDK-free, so the core suite runs across the declared
+    # Python support grid (requires-python >= 3.10) without a quantum SDK.
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Pull base image (retry + mirror fallback)
+        run: |
+          .github/scripts/pull-base-image.sh \
+            "docker.io/library/python:${{ matrix.python }}-slim" \
+            "public.ecr.aws/docker/library/python:${{ matrix.python }}-slim"
+
+      - name: core unit tests, SDK-free (containerized)
+        run: |
+          podman run --rm -v "$PWD:/work:Z" -w /work \
+            "docker.io/library/python:${{ matrix.python }}-slim" bash -euc "
+              pip install -q -e '.[dev]'
+              pytest -q -m 'not integration' --junitxml=core-junit-${{ matrix.python }}.xml
             "
 
       - name: Upload core test report
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: core-junit
-          path: core-junit.xml
+          name: core-junit-${{ matrix.python }}
+          path: core-junit-${{ matrix.python }}.xml
 
   image-and-integration:
     name: build image + integration + example gates
@@ -96,8 +121,16 @@ jobs:
             integration-junit.xml
 
   pip-consumer-path:
-    name: pip path (CLI + pytest plugin)
+    name: pip path (qiskit ${{ matrix.label }})
     runs-on: ubuntu-latest
+    # Exercise the consumer path against both ends of the declared qiskit range
+    # (qiskit>=1.2,<3): the supported floor and the latest 2.x.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { qiskit: "qiskit==1.2.*", label: "floor-1.2" }
+          - { qiskit: "qiskit<3", label: "latest-2.x" }
     steps:
       - uses: actions/checkout@v6
 
@@ -107,11 +140,12 @@ jobs:
             docker.io/library/python:3.12-slim \
             public.ecr.aws/docker/library/python:3.12-slim
 
-      - name: pip install and exercise the CLI and pytest plugin (containerized)
+      - name: pip install (pinned qiskit) and exercise the CLI and pytest plugin
         run: |
           podman run --rm -v "$PWD:/work:Z" -w /work \
             docker.io/library/python:3.12-slim bash -euc "
-              pip install -q '.[aer,dev]'
+              pip install -q '.[aer,dev]' '${{ matrix.qiskit }}'
+              python -c 'import qiskit; print(\"using qiskit\", qiskit.__version__)'
               # The pytest11 entry point must expose --shotgate after a pip install.
               pytest --help 2>/dev/null | grep -q -- '--shotgate'
               # CLI consumer path: gate a Bell workflow and emit a JUnit report.
@@ -128,11 +162,40 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: pip-path-junit
+          name: pip-path-junit-${{ matrix.label }}
           path: |
             cli-junit.xml
             plugin-junit.xml
 
+  braket-local:
+    name: braket local simulation
+    runs-on: ubuntu-latest
+    # The Braket backend's local-simulation path runs with no AWS account; the cloud
+    # path (named devices) needs AWS credentials and is not exercised in CI.
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Pull base image (retry + mirror fallback)
+        run: |
+          .github/scripts/pull-base-image.sh \
+            docker.io/library/python:3.12-slim \
+            public.ecr.aws/docker/library/python:3.12-slim
+
+      - name: braket local-simulation backend test (containerized)
+        run: |
+          podman run --rm -v "$PWD:/work:Z" -w /work \
+            docker.io/library/python:3.12-slim bash -euc "
+              pip install -q '.[braket,dev]'
+              pytest -q tests/test_braket_backend.py --junitxml=/work/braket-junit.xml
+            "
+
+      - name: Upload braket report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: braket-junit
+          path: braket-junit.xml
+
   terraform:
     name: terraform fmt + validate
     runs-on: ubuntu-latest

{shotgate-0.2.2 → shotgate-0.3.0}/CHANGELOG.md

@@ -6,6 +6,63 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-26
+
+> Bundles the work the roadmap sketched across several minor milestones (oracle breadth,
+> noise-aware validation, the AWS Braket backend) into one release after `0.2.2`.
+
+### Added
+
+- **AWS Braket backend (ADR-0011).** `provider: braket` runs the same workflows on Braket.
+  Local simulation needs **no AWS account** (omit `backend.name`); cloud devices are reached
+  by setting `backend.name` (e.g. `SV1`) and need configured AWS credentials. Dependencies
+  live in the `braket` extra (`pip install shotgate[braket]`); a dedicated CI job validates
+  the local path. Promotes `braket` from a planned to a working backend. The cloud path is
+  implemented but not yet validated on real Braket hardware.
+- **Noise-aware expected distributions: `chi_square` and `kl_divergence` can gate on
+  hardware (ADR-0010).** An optional `readout_error: { p0, p1 }` block transforms the ideal
+  `expected` through a calibration-derived per-qubit readout model, giving the test nonzero
+  mass on the device's error states. On the measured `ibm_fez` Bell counts this takes
+  `chi_square` from statistic 1.5e17 / p-value 0 to statistic 5.51 / p-value 0.138 (passes
+  at alpha 0.01); the readout parameters are declared from calibration, not fit to the
+  counts, so the gate stays honest. Partially lifts the ADR-0006 simulator-only policy.
+- **Declarative noise-model simulation on `local-aer` (ADR-0009).** A backend can carry a
+  `noise` block (`depolarizing_1q`/`depolarizing_2q`/`readout_p0`/`readout_p1`) so the
+  noise-aware `*-hardware` thresholds can be regression-tested in CI without a QPU. A
+  simulated-noisy Bell pair lands in the measured device regime (TVD ~0.12 vs the measured
+  `ibm_fez` 0.1284); a `bell-state-noisy-sim` example gates it against hardware-profile
+  bounds. Non-simulator backends ignore `noise`.
+- **Four new assertion oracles (5 -> 9), see ADR-0008:** `kl_divergence` (bound the
+  Kullback-Leibler divergence to an expected distribution, in bits; simulator-oriented
+  like `chi_square`), `shannon_entropy` (bound the distribution entropy in a min/max
+  window), `expectation_value` (bound the Pauli-Z product `<Z..Z>` in [-1, 1] via a
+  window or a target), and `most_frequent_outcome` (assert the modal state, optionally
+  above a probability). All are counts-based and keep the validation core SDK-free. A
+  `bell-state-observables` example exercises the new observable oracles. The JSON reporter
+  now serialises a non-finite metric (a diverged KL) as `null` so output stays valid.
+
+### Changed
+
+- **JUnit reports carry `timestamp` and `skipped`** attributes on the root and every
+  testsuite, for fuller xUnit-schema compliance in CI dashboards. Declared the supported
+  Python grid (3.10-3.13) as trove classifiers.
+- **Fail-closed validation (see ADR-0007).** A job that runs but declares no
+  assertions now **fails** by default, instead of silently passing a gate that checked
+  nothing; opt out with `--allow-empty` (CLI) or `allow_empty=True` (`Runner`).
+  Basis-state keys in `expected`, `state`, and `states` are validated at schema-parse
+  time: non-empty, `0`/`1` only, and a single consistent width, so a malformed key
+  (e.g. `"0x"`, or mixed `"0"`/`"11"`) raises a clear `ValidationError` instead of being
+  silently mis-compared. Both are behaviour changes, intended at `0.x`.
+
+### Fixed
+
+- **OpenQASM 3 circuits now load.** The `qasm3` circuit format was advertised in
+  the schema but failed at runtime: `qiskit.qasm3.loads` needs the
+  `qiskit-qasm3-import` package, which no extra declared. It is now a dependency of
+  the `aer` and `ibm` extras (and the published images), the loader raises an
+  actionable error if it is somehow absent, and a `bell-state-qasm3` example plus
+  loader tests cover the path.
+
 ## [0.2.2] - 2026-06-11
 
 ### Added
@@ -193,7 +250,8 @@ All notable changes to this project are documented here. The format is based on
   (with the math), getting-started guide, and ADRs.
 - **Examples**: Bell state, 3-qubit GHZ, and 2-qubit Grover workflows.
 
-[Unreleased]: https://github.com/coldqubit/shotgate/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/coldqubit/shotgate/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/coldqubit/shotgate/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/coldqubit/shotgate/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/coldqubit/shotgate/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/coldqubit/shotgate/compare/v0.1.1...v0.2.0

{shotgate-0.2.2 → shotgate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgate
-Version: 0.2.2
+Version: 0.3.0
 Summary: Container-native CI/CD quality gates for quantum circuits: statistically validate probabilistic output across simulators and QPUs.
 Project-URL: Homepage, https://github.com/coldqubit/shotgate
 Project-URL: Documentation, https://github.com/coldqubit/shotgate/tree/main/docs
@@ -15,6 +15,10 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: System :: Distributed Computing
@@ -25,13 +29,19 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Provides-Extra: aer
 Requires-Dist: qiskit-aer>=0.15; extra == 'aer'
+Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'aer'
 Requires-Dist: qiskit<3,>=1.2; extra == 'aer'
 Provides-Extra: all
+Requires-Dist: amazon-braket-sdk>=1.80; extra == 'all'
 Requires-Dist: qiskit-aer>=0.15; extra == 'all'
+Requires-Dist: qiskit-braket-provider>=0.4; extra == 'all'
 Requires-Dist: qiskit-ibm-runtime>=0.30; extra == 'all'
+Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'all'
 Requires-Dist: qiskit<3,>=1.2; extra == 'all'
 Provides-Extra: braket
 Requires-Dist: amazon-braket-sdk>=1.80; extra == 'braket'
+Requires-Dist: qiskit-braket-provider>=0.4; extra == 'braket'
+Requires-Dist: qiskit<3,>=1.2; extra == 'braket'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -40,6 +50,7 @@ Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Provides-Extra: ibm
 Requires-Dist: qiskit-ibm-runtime>=0.30; extra == 'ibm'
+Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'ibm'
 Requires-Dist: qiskit<3,>=1.2; extra == 'ibm'
 Provides-Extra: mitigation
 Requires-Dist: mitiq>=0.40; extra == 'mitigation'
@@ -123,15 +134,15 @@ jobs: [
 $ shotgate run examples/bell-state/workflow.yaml
 ─────────────────────────── shotgate :: bell-state ───────────────────────────
  job: bell-pair · aer_simulator · 8192 shots
- ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
- ┃ Assertion                 ┃ Result ┃ Detail                                        ┃
- ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
- │ chi-square p >= 0.01      │  PASS  │ chi-square=0.410 dof=1 p-value=0.5220          │
- │ TVD <= 0.03               │  PASS  │ total variation distance 0.0043 (<= 0.03)     │
- │ fidelity >= 0.99          │  PASS  │ Hellinger fidelity 1.0000 (>= 0.99)           │
- │ leakage <= 0.0            │  PASS  │ support leakage 0.0000 (<= 0.0)               │
- │ P(00) >= 0.45 and <= 0.55 │  PASS  │ P(00) = 0.4957                                │
- └───────────────────────────┴────────┴───────────────────────────────────────────────┘
+ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ ┃ Assertion                 ┃ Result ┃ Detail                                    ┃
+ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+ │ chi-square p >= 0.01      │  PASS  │ chi-square=0.410 dof=1 p-value=0.5220     │
+ │ TVD <= 0.03               │  PASS  │ total variation distance 0.0043 (<= 0.03) │
+ │ fidelity >= 0.99          │  PASS  │ Hellinger fidelity 1.0000 (>= 0.99)       │
+ │ leakage <= 0.0            │  PASS  │ support leakage 0.0000 (<= 0.0)           │
+ │ P(00) >= 0.45 and <= 0.55 │  PASS  │ P(00) = 0.4957                            │
+ └───────────────────────────┴────────┴───────────────────────────────────────────┘
  PASSED · 5/5 assertions · 0.214s
 ```
 
@@ -226,11 +237,15 @@ For hardware-isolated runs (each pipeline in a throwaway KVM micro-VM), see
 
 | Type | Oracle | Use it for |
 | --- | --- | --- |
-| `chi_square` | Pearson χ² GoF test (p-value vs α) | The rigorous statistical "does this match?" test |
-| `distribution_tvd` | Total variation distance (TVD) ≤ bound | Robust, shot-count-agnostic distribution check |
+| `chi_square` | Pearson χ² GoF test (p-value vs α) | Formal hypothesis test; **simulator-only** (see catalog) |
+| `distribution_tvd` | Total variation distance (TVD) ≤ bound | Default distribution check; interpretable, shot-count-agnostic |
 | `hellinger_fidelity` | Classical fidelity ≥ threshold | Fidelity tracking against an ideal distribution |
 | `state_probability` | Marginal P(state) in a window / ≈ target | Single-outcome amplitude checks (e.g. Grover) |
 | `allowed_states` | Probability mass outside support ≤ budget | Structural/leakage guarantees (e.g. GHZ corners) |
+| `kl_divergence` | KL D(obs‖exp) ≤ bound (bits) | Information-theoretic distance; **simulator-only** (zero-support) |
+| `shannon_entropy` | Entropy in a min/max window (bits) | Assert the intended randomness/concentration |
+| `expectation_value` | `<Z..Z>` in [-1, 1] via window / target | Correlation/parity observable tracking |
+| `most_frequent_outcome` | Modal state (optional min probability) | Single intended answer (e.g. Grover) |
 
 Full reference: [`docs/assertions.md`](docs/assertions.md). The statistical core is pure Python
 (no SciPy), including a from-scratch χ² survival function via the regularised incomplete gamma
@@ -271,7 +286,7 @@ The same artifact therefore runs in a small CI container and against a real QPU.
 ```text
 shotgate/
 ├── src/shotgate/          # the package (validation core, backends, runner, CLI, pytest plugin)
-├── examples/              # runnable workflows: bell, ghz, grover
+├── examples/              # runnable workflows: bell/ghz/grover + backend & oracle variants
 ├── tests/                 # unit tests (core) + integration tests (gated on aer)
 ├── infra/
 │   ├── terraform/         # IaC module: "quantum workflow as code"
@@ -288,7 +303,7 @@ shotgate/
 | --- | --- |
 | `local-aer` (Qiskit Aer simulator) | **Working**, default, baked into the image |
 | `ibm` (IBM Quantum via Qiskit Runtime) | **Validated on real hardware** (`ibm_fez`, 2026-06-11: Bell/GHZ/Grover gates passed at 4096 shots; [measured baseline](docs/hardware-validation.md)) |
-| `braket` (AWS Braket) | **Planned** (not selectable yet) |
+| `braket` (AWS Braket via qiskit-braket-provider) | **Working: local simulation** (no AWS account). Cloud devices need AWS credentials; not yet validated on real Braket hardware. |
 | Error mitigation ([Mitiq](https://mitiq.readthedocs.io/)) | **Planned** |
 
 ## Roadmap
@@ -296,14 +311,19 @@ shotgate/
 - **v0.1:** YAML workflows, local Aer backend, χ²/TVD/fidelity/structural oracles,
   JUnit/JSON/MD reporters, Podman and KVM/QEMU isolation, Terraform module, pytest plugin,
   PyPI package, published GHCR image with an IBM-enabled variant.
-- **v0.2 (now):** statistical gates **validated against real quantum hardware** (`ibm_fez`,
+- **v0.2:** statistical gates **validated against real quantum hardware** (`ibm_fez`,
   2026-06-11, Bell/GHZ/Grover at 4096 shots; measured baseline and runbook in
   [`docs/hardware-validation.md`](docs/hardware-validation.md)), hardware example gates for
   GHZ and Grover, and a dispatchable QPU validation workflow.
-- **v0.3:** noise-model simulation, a minimal AWS Braket backend, error mitigation via
-  [Mitiq](https://mitiq.readthedocs.io/), circuit fixtures and property-based generation,
-  multi-backend differential testing, a Helm chart, and an optional OpenTelemetry exporter
-  for the telemetry layer (kept out of the core dependencies).
+- **v0.3.0 (latest release):** the OpenQASM 3 fix and fail-closed validation, four more
+  oracles (`kl_divergence`, `shannon_entropy`, `expectation_value`, `most_frequent_outcome`),
+  declarative noise-model simulation and noise-aware expected distributions (so
+  `chi_square`/`kl_divergence` can gate on hardware), and the AWS Braket backend (local
+  simulation; the cloud path awaits validation on real hardware).
+- **Planned:** error mitigation via [Mitiq](https://mitiq.readthedocs.io/), multi-backend
+  differential testing, circuit fixtures and property-based generation, a Helm chart, an
+  optional OpenTelemetry exporter for the telemetry layer (kept out of the core
+  dependencies), and validation of the Braket cloud path on real hardware.
 
 See [`CHANGELOG.md`](CHANGELOG.md) and the [ADRs](docs/adr/) for decisions and rationale.
 

{shotgate-0.2.2 → shotgate-0.3.0}/README.md

@@ -76,15 +76,15 @@ jobs: [
 $ shotgate run examples/bell-state/workflow.yaml
 ─────────────────────────── shotgate :: bell-state ───────────────────────────
  job: bell-pair · aer_simulator · 8192 shots
- ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
- ┃ Assertion                 ┃ Result ┃ Detail                                        ┃
- ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
- │ chi-square p >= 0.01      │  PASS  │ chi-square=0.410 dof=1 p-value=0.5220          │
- │ TVD <= 0.03               │  PASS  │ total variation distance 0.0043 (<= 0.03)     │
- │ fidelity >= 0.99          │  PASS  │ Hellinger fidelity 1.0000 (>= 0.99)           │
- │ leakage <= 0.0            │  PASS  │ support leakage 0.0000 (<= 0.0)               │
- │ P(00) >= 0.45 and <= 0.55 │  PASS  │ P(00) = 0.4957                                │
- └───────────────────────────┴────────┴───────────────────────────────────────────────┘
+ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ ┃ Assertion                 ┃ Result ┃ Detail                                    ┃
+ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+ │ chi-square p >= 0.01      │  PASS  │ chi-square=0.410 dof=1 p-value=0.5220     │
+ │ TVD <= 0.03               │  PASS  │ total variation distance 0.0043 (<= 0.03) │
+ │ fidelity >= 0.99          │  PASS  │ Hellinger fidelity 1.0000 (>= 0.99)       │
+ │ leakage <= 0.0            │  PASS  │ support leakage 0.0000 (<= 0.0)           │
+ │ P(00) >= 0.45 and <= 0.55 │  PASS  │ P(00) = 0.4957                            │
+ └───────────────────────────┴────────┴───────────────────────────────────────────┘
  PASSED · 5/5 assertions · 0.214s
 ```
 
@@ -179,11 +179,15 @@ For hardware-isolated runs (each pipeline in a throwaway KVM micro-VM), see
 
 | Type | Oracle | Use it for |
 | --- | --- | --- |
-| `chi_square` | Pearson χ² GoF test (p-value vs α) | The rigorous statistical "does this match?" test |
-| `distribution_tvd` | Total variation distance (TVD) ≤ bound | Robust, shot-count-agnostic distribution check |
+| `chi_square` | Pearson χ² GoF test (p-value vs α) | Formal hypothesis test; **simulator-only** (see catalog) |
+| `distribution_tvd` | Total variation distance (TVD) ≤ bound | Default distribution check; interpretable, shot-count-agnostic |
 | `hellinger_fidelity` | Classical fidelity ≥ threshold | Fidelity tracking against an ideal distribution |
 | `state_probability` | Marginal P(state) in a window / ≈ target | Single-outcome amplitude checks (e.g. Grover) |
 | `allowed_states` | Probability mass outside support ≤ budget | Structural/leakage guarantees (e.g. GHZ corners) |
+| `kl_divergence` | KL D(obs‖exp) ≤ bound (bits) | Information-theoretic distance; **simulator-only** (zero-support) |
+| `shannon_entropy` | Entropy in a min/max window (bits) | Assert the intended randomness/concentration |
+| `expectation_value` | `<Z..Z>` in [-1, 1] via window / target | Correlation/parity observable tracking |
+| `most_frequent_outcome` | Modal state (optional min probability) | Single intended answer (e.g. Grover) |
 
 Full reference: [`docs/assertions.md`](docs/assertions.md). The statistical core is pure Python
 (no SciPy), including a from-scratch χ² survival function via the regularised incomplete gamma
@@ -224,7 +228,7 @@ The same artifact therefore runs in a small CI container and against a real QPU.
 ```text
 shotgate/
 ├── src/shotgate/          # the package (validation core, backends, runner, CLI, pytest plugin)
-├── examples/              # runnable workflows: bell, ghz, grover
+├── examples/              # runnable workflows: bell/ghz/grover + backend & oracle variants
 ├── tests/                 # unit tests (core) + integration tests (gated on aer)
 ├── infra/
 │   ├── terraform/         # IaC module: "quantum workflow as code"
@@ -241,7 +245,7 @@ shotgate/
 | --- | --- |
 | `local-aer` (Qiskit Aer simulator) | **Working**, default, baked into the image |
 | `ibm` (IBM Quantum via Qiskit Runtime) | **Validated on real hardware** (`ibm_fez`, 2026-06-11: Bell/GHZ/Grover gates passed at 4096 shots; [measured baseline](docs/hardware-validation.md)) |
-| `braket` (AWS Braket) | **Planned** (not selectable yet) |
+| `braket` (AWS Braket via qiskit-braket-provider) | **Working: local simulation** (no AWS account). Cloud devices need AWS credentials; not yet validated on real Braket hardware. |
 | Error mitigation ([Mitiq](https://mitiq.readthedocs.io/)) | **Planned** |
 
 ## Roadmap
@@ -249,14 +253,19 @@ shotgate/
 - **v0.1:** YAML workflows, local Aer backend, χ²/TVD/fidelity/structural oracles,
   JUnit/JSON/MD reporters, Podman and KVM/QEMU isolation, Terraform module, pytest plugin,
   PyPI package, published GHCR image with an IBM-enabled variant.
-- **v0.2 (now):** statistical gates **validated against real quantum hardware** (`ibm_fez`,
+- **v0.2:** statistical gates **validated against real quantum hardware** (`ibm_fez`,
   2026-06-11, Bell/GHZ/Grover at 4096 shots; measured baseline and runbook in
   [`docs/hardware-validation.md`](docs/hardware-validation.md)), hardware example gates for
   GHZ and Grover, and a dispatchable QPU validation workflow.
-- **v0.3:** noise-model simulation, a minimal AWS Braket backend, error mitigation via
-  [Mitiq](https://mitiq.readthedocs.io/), circuit fixtures and property-based generation,
-  multi-backend differential testing, a Helm chart, and an optional OpenTelemetry exporter
-  for the telemetry layer (kept out of the core dependencies).
+- **v0.3.0 (latest release):** the OpenQASM 3 fix and fail-closed validation, four more
+  oracles (`kl_divergence`, `shannon_entropy`, `expectation_value`, `most_frequent_outcome`),
+  declarative noise-model simulation and noise-aware expected distributions (so
+  `chi_square`/`kl_divergence` can gate on hardware), and the AWS Braket backend (local
+  simulation; the cloud path awaits validation on real hardware).
+- **Planned:** error mitigation via [Mitiq](https://mitiq.readthedocs.io/), multi-backend
+  differential testing, circuit fixtures and property-based generation, a Helm chart, an
+  optional OpenTelemetry exporter for the telemetry layer (kept out of the core
+  dependencies), and validation of the Braket cloud path on real hardware.
 
 See [`CHANGELOG.md`](CHANGELOG.md) and the [ADRs](docs/adr/) for decisions and rationale.
 

{shotgate-0.2.2 → shotgate-0.3.0}/docs/README.md

@@ -1,5 +1,14 @@
 # shotgate documentation
 
+shotgate runs container-native CI/CD quality gates for quantum circuits: it executes a
+circuit on a simulator or a real quantum processing unit (QPU) and gates the pipeline on
+the *statistical* properties of the measured shot distribution (chi-square goodness-of-fit,
+total variation distance, Hellinger fidelity, support leakage) rather than on exact
+equality, which probabilistic output makes meaningless. New here? Read
+[Getting Started](getting-started.md) first, then the
+[Workflow Specification](workflow-spec.md) for the YAML schema and the
+[Assertion Catalog](assertions.md) for the oracles and how to set thresholds.
+
 | Document | What it covers |
 | --- | --- |
 | [Getting Started](getting-started.md) | Zero to a passing quantum gate with Podman. |

{shotgate-0.2.2 → shotgate-0.3.0}/docs/adr/0006-hardware-oracle-policy.md

@@ -18,9 +18,11 @@ came out of those runs:
    on the same counts (TVD 0.1350, fidelity 0.8650, leakage 0.1350, P(`00`) 0.4343).
    The ideal expected distribution `{00: 0.5, 11: 0.5}` assigns probability 0 to
    the error states `01`/`10`; the implementation floors expected counts at
-   `_MIN_EXPECTED = 1e-12` to keep the statistic finite, so each of the 553 leaked
-   shots contributes on the order of `observed^2 / 1e-12`. Against an ideal support,
-   any device leakage forces rejection regardless of thresholds.
+   `_MIN_EXPECTED = 1e-12` to keep the statistic finite, so each error state
+   contributes `observed^2 / 1e-12` (the 304 and 249 counts in `10`/`01` sum to about
+   `1.5e17`, a magnitude set by the floor, not the data). Against an ideal support,
+   any device leakage forces rejection regardless of thresholds; the rejection is
+   floor-independent even though the statistic's magnitude is not.
 
 ## Decision
 

shotgate-0.3.0/docs/adr/0007-fail-closed-workflow-validation.md

@@ -0,0 +1,49 @@
+# ADR-0007: Fail-closed workflow validation (empty gates and malformed expected distributions)
+
+- **Status:** Accepted
+- **Date:** 2026-06-26
+
+## Context
+
+Two ways a shotgate gate could pass while not actually validating anything were found
+by exercising the runner and the schema:
+
+1. **A job with no assertions reported PASS.** The runner computed
+   `all(o.passed for o in outcomes)`, and `all([])` is `True`, so a workflow whose
+   jobs declared `assertions: []` passed the pipeline while checking nothing. A quality
+   gate that can be green without testing is a correctness hazard, not a convenience.
+2. **Expected distributions accepted any string key.** The `expected` maps of the
+   distribution oracles, and the `state`/`states` fields, were typed `dict[str, float]`
+   / `str` / `list[str]` with no constraint, so a 3-bit key against a 2-qubit circuit,
+   mixed-width keys, or a typo like `"0x"` parsed cleanly and were then silently
+   mis-compared, producing a wrong-but-green result instead of an error.
+
+## Decision
+
+shotgate validates fail-closed: a gate that cannot meaningfully check something is an
+error, not a pass.
+
+1. **An empty gate fails by default.** A job that runs but declares no assertions is
+   marked failed with an explanatory message. The behaviour is opt-out: `--allow-empty`
+   on `shotgate run` (or `allow_empty=True` on `Runner`) restores a passing empty job
+   for the rare case where that is intended (a placeholder, a circuit-only smoke run).
+2. **Basis-state keys are validated at schema-parse time.** Keys in `expected`, and the
+   `state`/`states` fields, must be non-empty, contain only `0`/`1` (whitespace from
+   multi-register formatting is stripped, matching `metrics.clean_key`), and all
+   describe the same number of bits. A malformed key now raises a pydantic
+   `ValidationError` with the offending key named.
+
+## Consequences
+
+- **+** No silent no-op gates: a green shotgate run means assertions actually ran.
+- **+** Distribution typos fail fast at load time with a clear message, the same way the
+  strict (`extra="forbid"`) schema already catches unknown fields.
+- **+** The cross-check against the circuit's qubit width is now well-defined to add at
+  evaluate time later, because the keys are guaranteed internally consistent.
+- **-** This is a behaviour change: a previously-passing empty gate now fails, and a
+  workflow with a malformed key that previously parsed now raises. Both are pre-1.0
+  (`0.x`) and intended; the empty-gate change is documented in `CHANGELOG.md`, and the
+  escape hatch (`--allow-empty`) covers the legitimate case.
+- The validation is internal-consistency only (binary, equal width). Matching the key
+  width to the executed circuit's classical-bit count is a separate evaluate-time check
+  deferred to a later version.

shotgate-0.3.0/docs/adr/0008-counts-based-oracle-expansion.md

@@ -0,0 +1,52 @@
+# ADR-0008: Counts-based oracle expansion (divergence, entropy, expectation, mode)
+
+- **Status:** Accepted
+- **Date:** 2026-06-26
+
+## Context
+
+shotgate shipped five assertion oracles: a distance test (`distribution_tvd`), a
+goodness-of-fit test (`chi_square`), a closeness score (`hellinger_fidelity`), a marginal
+(`state_probability`), and a structural/leakage bound (`allowed_states`). The quantum
+software-testing field, and adjacent tools such as QUTest, cover a wider assertion set,
+notably observable expectation values, distribution entropy, and information-theoretic
+divergence. These are real gaps for a tool that markets itself as the statistical quality
+gate for quantum circuits.
+
+The constraint that has served the project well is that oracles are **counts-based and
+pure-Python**: each assertion's `evaluate(counts, shots)` operates only on a histogram of
+measured bitstrings, so the validation core never imports a quantum SDK (ADR-0002).
+
+## Decision
+
+Add four oracles that stay inside that contract, taking the count from five to nine:
+
+1. `kl_divergence`: bound the Kullback-Leibler divergence `D(observed || expected)` in bits.
+2. `shannon_entropy`: bound the distribution's Shannon entropy (min/max bits).
+3. `expectation_value`: bound the Pauli-Z product `<Z_{q0} Z_{q1} ...>` in `[-1, 1]`, read
+   off the computational-basis counts as a parity expectation.
+4. `most_frequent_outcome`: assert the modal measured state, optionally above a probability.
+
+Two related oracles are **deferred** because they do not fit the `evaluate(counts, shots)`
+contract:
+
+- **Arbitrary-Pauli observables** (e.g. `<X>`, `<Y>`, entanglement witnesses) need
+  basis-change measurement circuits, not just computational-basis counts. `expectation_value`
+  is therefore Z-basis only for now.
+- **Structural assertions on the circuit** (depth, width, gate-set membership) need the
+  circuit/telemetry, which `evaluate` does not receive; they require a signature change and
+  are left to a later version.
+
+## Consequences
+
+- **+** Closes the distribution/observable breadth gap while keeping the core SDK-free and
+  unit-tested against analytic values (`<Z0 Z1> = +1` for a Bell pair, `H = 1` bit for a
+  balanced two-outcome distribution, `D(p||p) = 0`).
+- **+** `expectation_value` gives a hardware-friendly single-number observable to track,
+  complementing the distribution oracles.
+- **-** `kl_divergence` inherits the zero-support pathology of `chi_square`: an ideal
+  `expected` that assigns probability 0 to a device's error states diverges to infinity, so
+  KL is simulator-oriented unless `expected` is noise-aware (the v0.5 work). The reporter
+  serialises a non-finite metric as JSON `null` so output stays valid.
+- **-** `expectation_value` covers only Z-basis products; the broader Pauli and
+  entanglement-witness oracles remain future work, as do the circuit-structural oracles.

shotgate-0.3.0/docs/adr/0009-noise-model-simulation.md

@@ -0,0 +1,55 @@
+# ADR-0009: Declarative noise-model simulation on the local Aer backend
+
+- **Status:** Accepted
+- **Date:** 2026-06-26
+
+## Context
+
+The `*-hardware` example gates carry noise-aware thresholds (Bell: TVD <= 0.15, fidelity
+>= 0.85, leakage <= 0.15; full table in `docs/hardware-validation.md` section 4). Until now
+those thresholds could only be exercised against a real QPU, which is queued and metered:
+there was no way to regression-test the noise-aware profiles in ordinary CI, and a profile
+could silently rot (become too loose or too tight) between hardware runs.
+
+A measurement on this codebase showed that an Aer noise model with a per-gate depolarizing
+error plus a readout error reproduces the measured `ibm_fez` Bell regime closely (simulated
+TVD 0.1223 against a measured 0.1284), so a simulated device is a faithful enough proxy to
+gate the noise-aware thresholds offline.
+
+## Decision
+
+Add an optional, declarative `noise` block to a backend spec, consumed by the `local-aer`
+backend:
+
+```yaml
+backend:
+  provider: local-aer
+  noise:
+    depolarizing_1q: 0.004   # per single-qubit gate
+    depolarizing_2q: 0.012   # per two-qubit gate
+    readout_p0: 0.06         # P(measure 1 | prepared 0)
+    readout_p1: 0.07         # P(measure 0 | prepared 1)
+```
+
+- `NoiseSpec` is a strict (`extra="forbid"`) pydantic model with each parameter bounded in
+  `[0, 1]`; an all-zero spec is identical to the noiseless simulator.
+- The spec rides through the backend `options` dict (set by the registry) so the `Backend`
+  ABC stays minimal. The `local-aer` backend separates it out, builds a Qiskit Aer
+  `NoiseModel` (uniform depolarizing on common 1- and 2-qubit gates, plus an assignment
+  readout error), and records a `noisy` flag in the result metadata.
+- Real-hardware backends ignore `noise` (a device carries its own noise).
+
+## Consequences
+
+- **+** The noise-aware `*-hardware` thresholds become testable in CI with zero QPU time; a
+  `bell-state-noisy-sim` example gates a simulated-noisy Bell pair against hardware-profile
+  bounds.
+- **+** Contributors can develop and tune noise-aware thresholds offline before spending a
+  hardware run.
+- **-** The model is an approximate, uniform device proxy, not a calibration: it applies one
+  depolarizing rate per gate class and one readout matrix to every qubit, and only to the
+  enumerated gate names (others stay noiseless). It does not capture crosstalk, coherent
+  errors, or qubit-specific calibration. It is a threshold-exercising tool, not a device
+  digital twin.
+- **-** `noise` is meaningful only for the `local-aer` backend; setting it on `ibm` is a
+  silent no-op (documented).