shotgate 0.2.1__tar.gz → 0.2.2__tar.gz

shotgate-0.2.2/.github/workflows/dockerhub-mirror.yml

@@ -0,0 +1,91 @@
+name: dockerhub-mirror
+
+# Mirror an already-published GHCR image set to Docker Hub, then sync this repo's
+# README and tagline onto the Docker Hub repository page so the listing matches the
+# source. GHCR stays the canonical registry; Docker Hub is a convenience mirror for
+# discovery and the familiar `docker pull`. Runs on release (via workflow_call from
+# release.yml) and on demand (workflow_dispatch) to re-mirror or back-fill any version.
+#
+# Credentials live in the `dockerhub` environment: DOCKERHUB_USERNAME and
+# DOCKERHUB_TOKEN (a Docker Hub access token), and optionally DOCKERHUB_NAMESPACE
+# to push under a Hub organization instead of the username. Absent credentials
+# (a fork), the mirror step is skipped rather than failing.
+#
+# The README sync uses peter-evans/dockerhub-description, which drives the Docker
+# Hub HTTP API. That API accepts a personal access token only if it is scoped
+# read/write/delete; if DOCKERHUB_TOKEN is scoped narrower, set
+# DOCKERHUB_DESCRIPTION_PASSWORD in the `dockerhub` environment (the account
+# password or a read/write/delete token) and it is used in preference. The sync
+# step is non-fatal (`continue-on-error`): a description failure never blocks the
+# image mirror or the release.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to mirror from GHCR to Docker Hub (e.g. 0.2.1)"
+        required: true
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: read
+
+jobs:
+  mirror:
+    name: mirror GHCR -> Docker Hub
+    runs-on: ubuntu-latest
+    environment: dockerhub
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+      DOCKERHUB_NAMESPACE: ${{ secrets.DOCKERHUB_NAMESPACE }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Compute Docker Hub repository
+        id: hub
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        run: |
+          # Namespace defaults to the Hub username; DOCKERHUB_NAMESPACE overrides
+          # it to push under a Hub organization. Same rule as the mirror step.
+          NS="${DOCKERHUB_NAMESPACE:-$DOCKERHUB_USERNAME}"
+          echo "repository=${NS,,}/shotgate" >> "$GITHUB_OUTPUT"
+
+      - name: Mirror the version, latest, and -ibm tags
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACTOR: ${{ github.actor }}
+          REPO: ${{ github.repository }}
+          VERSION: ${{ inputs.version }}
+          HUB_REPO: ${{ steps.hub.outputs.repository }}
+        run: |
+          V="${VERSION#v}"                      # tolerate a leading 'v'
+          GHCR="ghcr.io/${REPO,,}"
+          DH="docker.io/${HUB_REPO}"
+          echo "$GH_TOKEN" | podman login ghcr.io -u "$ACTOR" --password-stdin
+          echo "$DOCKERHUB_TOKEN" | podman login docker.io -u "$DOCKERHUB_USERNAME" --password-stdin
+          for tag in "$V" latest "${V}-ibm" latest-ibm; do
+            podman pull "${GHCR}:${tag}"
+            podman tag "${GHCR}:${tag}" "${DH}:${tag}"
+            podman push "${DH}:${tag}"
+          done
+          echo "Mirrored ${GHCR}:{${V},latest,${V}-ibm,latest-ibm} -> ${DH}"
+
+      # Keep the Docker Hub repository page in sync with the source: the repo
+      # README becomes the full description, the project tagline the short one.
+      - name: Sync Docker Hub README and short description
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        continue-on-error: true
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_DESCRIPTION_PASSWORD || secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ steps.hub.outputs.repository }}
+          short-description: "Container-native CI/CD quality gates for quantum circuits"
+          readme-filepath: ./README.md

{shotgate-0.2.1 → shotgate-0.2.2}/.github/workflows/pypi-smoke.yml

@@ -40,7 +40,16 @@ jobs:
             docker.io/library/python:3.12-slim bash -euc '
               SPEC="shotgate[aer]"
               [ -n "$REQUESTED_VERSION" ] && SPEC="shotgate[aer]==$REQUESTED_VERSION"
-              pip install -q --no-cache-dir "$SPEC" pytest
+              # A freshly released version can lag for several minutes in the PyPI
+              # /simple/ index that pip reads, even after the files are live and the
+              # per-release JSON shows them (observed ~10 min on 2026-06-11). Retry
+              # generously so dispatching right after a release tolerates the lag.
+              for attempt in $(seq 1 20); do
+                pip install -q --no-cache-dir "$SPEC" pytest && break
+                echo "install attempt ${attempt}/20 failed (index may be propagating); retrying in 45s" >&2
+                sleep 45
+              done
+              pip show shotgate >/dev/null  # fail the step if all attempts failed
               echo "--- installed:"
               pip show shotgate | sed -n "1,2p"
               echo "--- CLI gate (exit 0 expected):"

{shotgate-0.2.1 → shotgate-0.2.2}/.github/workflows/release.yml

@@ -44,12 +44,6 @@ jobs:
     name: publish container image to GHCR
     runs-on: ubuntu-latest
     needs: build-dist
-    # Mapped at job level so the optional Docker Hub step can guard on env (the
-    # secrets context is not available inside a step-level if:).
-    env:
-      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
-      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
-      DOCKERHUB_NAMESPACE: ${{ secrets.DOCKERHUB_NAMESPACE }}
     steps:
       - uses: actions/checkout@v6
 
@@ -104,31 +98,16 @@ jobs:
           podman push "${IMG}:${VERSION}-ibm"
           podman push "${IMG}:latest-ibm"
 
-      # Optional Docker Hub mirror. GHCR is the canonical registry; this only runs
-      # when both DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repository secrets exist,
-      # so the release never fails for the absence of a Docker Hub account. To
-      # enable: create a Docker Hub repo and an access token, then add those two
-      # secrets. The Hub namespace defaults to the GitHub owner; override with the
-      # DOCKERHUB_NAMESPACE secret if your Hub org differs.
-      - name: Mirror images to Docker Hub (optional)
-        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
-        env:
-          VERSION: ${{ steps.meta.outputs.version }}
-          SHA: ${{ steps.meta.outputs.sha }}
-          DH_USER: ${{ env.DOCKERHUB_USERNAME }}
-          DH_TOKEN: ${{ env.DOCKERHUB_TOKEN }}
-          DH_NS: ${{ env.DOCKERHUB_NAMESPACE }}
-          GHCR_IMG: ${{ steps.meta.outputs.image }}
-          OWNER: ${{ github.repository_owner }}
-        run: |
-          NS="${DH_NS:-$OWNER}"
-          DH="docker.io/${NS,,}/shotgate"
-          echo "$DH_TOKEN" | podman login docker.io -u "$DH_USER" --password-stdin
-          # Retag the images already built above (no rebuild) and push the same set.
-          for tag in "$VERSION" "$SHA" latest "${VERSION}-ibm" latest-ibm; do
-            podman tag "${GHCR_IMG}:${tag}" "${DH}:${tag}"
-            podman push "${DH}:${tag}"
-          done
+  # Mirror the just-published GHCR images to Docker Hub (optional convenience
+  # registry). Delegated to the reusable dockerhub-mirror workflow, which is also
+  # dispatchable on its own to re-mirror any version. Skipped automatically when
+  # the dockerhub environment has no credentials.
+  mirror-dockerhub:
+    needs: publish-image
+    uses: ./.github/workflows/dockerhub-mirror.yml
+    with:
+      version: ${{ github.ref_name }}
+    secrets: inherit
 
   publish-pypi:
     name: publish to PyPI (trusted publishing)
@@ -173,18 +152,20 @@ jobs:
           {
             echo "## Install ${GITHUB_REF_NAME}"
             echo
-            echo "Everything below is downloadable straight from GitHub. No PyPI or Docker Hub account is needed."
+            echo "The package is on **PyPI** and the image on the **GitHub Container Registry (GHCR)** for convenience (the usual one-liners below). If you would rather not use a package index at all, the wheel attached to this release and the GHCR image are both pullable straight from GitHub, no extra account needed."
             echo
-            echo "**Python package** (wheel + sdist attached to this release):"
+            echo "**Python package** (PyPI, or the attached wheel):"
             echo '```bash'
+            echo "pip install 'shotgate[aer]==${V}'"
+            echo "# or straight from this release, no index:"
             echo "pip install https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/shotgate-${V}-py3-none-any.whl"
-            echo "# or, from any index that mirrors it:  pip install 'shotgate[aer]==${V}'"
             echo '```'
             echo
-            echo "**Container** (published to GitHub Container Registry):"
+            echo "**Container** (GHCR, canonical; add the \`-ibm\` tag suffix for the QPU-capable variant):"
             echo '```bash'
-            echo "podman pull ghcr.io/${GITHUB_REPOSITORY}:${V}        # add -ibm for the QPU-capable variant"
+            echo "podman pull ghcr.io/${GITHUB_REPOSITORY}:${V}"
             echo "podman run --rm -v \"\$PWD:/work:Z\" -w /work ghcr.io/${GITHUB_REPOSITORY}:${V} run examples/bell-state/workflow.yaml"
+            echo "# also mirrored to Docker Hub:  docker.io/${GITHUB_REPOSITORY}:${V}"
             echo '```'
             echo
             echo "---"

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

@@ -6,7 +6,31 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-*Nothing yet.*
+## [0.2.2] - 2026-06-11
+
+### Added
+
+- **Three Architecture Decision Records.** ADR-0004 (rename `qforge` to `shotgate`,
+  including the breaking `apiVersion` change), ADR-0005 (license MIT to
+  AGPL-3.0-or-later to Apache-2.0, and the DCO inbound policy), and ADR-0006
+  (`chi_square` simulator-only, noise-aware hardware thresholds), completing the
+  ADR series against the GOVERNANCE.md criteria.
+- **Docker Hub repository page sync.** After mirroring images, the `dockerhub-mirror`
+  workflow now pushes the repository README and the project tagline to the Docker Hub
+  repository description, so the Hub listing tracks the source. The step is non-fatal:
+  a description-API failure never blocks the image mirror or the release.
+
+### Changed
+
+- **Docker Hub mirroring is a reusable, dispatchable workflow.** The mirror moved from an
+  inline release job to `dockerhub-mirror.yml` (`workflow_call` from the release plus
+  `workflow_dispatch` to back-fill any version), with credentials read from the
+  `dockerhub` environment (`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, optional
+  `DOCKERHUB_NAMESPACE`) instead of repository secrets.
+- **Reporter copy uses ASCII separators.** The Markdown summary title format is now
+  ``## shotgate: `name` (status)``, the no-assertion row prints `n/a`, and the plain
+  console fallback separates label and message with a colon; previously all three used
+  an em-dash. JUnit and JSON payloads are unchanged.
 
 ## [0.2.1] - 2026-06-11
 
@@ -102,7 +126,7 @@ All notable changes to this project are documented here. The format is based on
   moved to the new name. The canonical home is `github.com/coldqubit/shotgate` and the
   published image is `ghcr.io/coldqubit/shotgate`.
 - **Pull-first usage.** Documentation now leads with `podman run
-  ghcr.io/coldqubit/shotgate …`; building from source is the contributor fallback.
+  ghcr.io/coldqubit/shotgate ...`; building from source is the contributor fallback.
 - **Honest extras.** `braket` and `mitigation` are marked *planned* and removed from the
   installable `all` extra, since no Braket backend or Mitiq integration ships yet.
   `--backend braket` now fails fast at schema validation with a clear message.
@@ -123,7 +147,7 @@ All notable changes to this project are documented here. The format is based on
 - **Hardened IBM/QPU backend**: robust counts extraction from named classical registers
   (with a clear error on unexpected result shapes), corrected Runtime channel default,
   a token-gated smoke test, and an `[ibm]`-baked image variant (build arg
-  `SHOTGATE_EXTRAS="aer,ibm"`, published as the `:…-ibm` image tag).
+  `SHOTGATE_EXTRAS="aer,ibm"`, published as the `:...-ibm` image tag).
 - **Noise-tolerant example** (`examples/bell-state-hardware/`) with relaxed thresholds
   for real-device runs, plus a documented simulator-vs-QPU threshold split.
 - **`docs/hardware-validation.md`**: a step-by-step plan and acceptance matrix for
@@ -169,7 +193,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.1...HEAD
+[Unreleased]: https://github.com/coldqubit/shotgate/compare/v0.2.2...HEAD
+[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
 [0.1.1]: https://github.com/coldqubit/shotgate/compare/v0.1.0...v0.1.1

{shotgate-0.2.1 → shotgate-0.2.2}/CONTRIBUTING.md

@@ -7,11 +7,11 @@ favors small, well-tested, well-reasoned changes.
 
 - Be kind; follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 - Discuss non-trivial changes in an issue first (especially new assertion oracles or
-  backends — they have design implications).
+  backends, which have design implications).
 - Keep the **validation core dependency-free** (standard library + pydantic). Quantum
   SDKs are optional extras, imported lazily inside backends only.
 
-## Development workflow (containers only — no host installs)
+## Development workflow (containers only, no host installs)
 
 Everything runs through Podman via the `Makefile`:
 

{shotgate-0.2.1 → shotgate-0.2.2}/Containerfile

@@ -1,4 +1,4 @@
-# shotgate runtime image — built and run with Podman (rootless-friendly).
+# shotgate runtime image, built and run with Podman (rootless-friendly).
 #
 # Multi-stage:
 #   builder  -> installs shotgate + the Aer simulator into an isolated venv

{shotgate-0.2.1 → shotgate-0.2.2}/Makefile

@@ -1,4 +1,4 @@
-# shotgate — Podman/QEMU task runner.
+# shotgate: Podman/QEMU task runner.
 #
 # Everything runs in containers or VMs; nothing is installed on the host.
 # Override any variable on the command line, e.g.  make run WORKFLOW=examples/ghz-state/workflow.yaml
@@ -14,7 +14,7 @@ MOUNT       := -v "$(CURDIR):/work:Z" -w /work
 RUN         := $(PODMAN) run --rm $(MOUNT)
 
 # Map the invoking host user through the container's user namespace so that
-# report files written to the bind mount are owned by you — while the image
+# report files written to the bind mount are owned by you, while the image
 # keeps its non-root default user. The standard Podman idiom for this case.
 USERMAP     := --userns=keep-id --user $(shell id -u):$(shell id -g)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgate
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -138,7 +138,7 @@ $ shotgate run examples/bell-state/workflow.yaml
 The same run drops into a pipeline through the Markdown reporter (`--markdown`), rendered
 as a step summary or a PR comment:
 
-> ## shotgate: `bell-state` — ✅ passed
+> ## shotgate: `bell-state` (✅ passed)
 >
 > - Jobs: **1**, failed: **0**
 > - Assertions: **5**, failed: **0**
@@ -180,6 +180,10 @@ podman run --rm -e SHOTGATE_IBM_TOKEN \
   run examples/bell-state-hardware/workflow.yaml --backend ibm
 ```
 
+The same images are mirrored to Docker Hub if you prefer it: swap the registry prefix for
+`docker.io/coldqubit/shotgate` (tags `latest`, `latest-ibm`, and each version). GHCR is the
+canonical registry; the Docker Hub copy is a convenience mirror.
+
 ### Path B: pip (CLI and pytest plugin)
 
 Install the package with the backend extra you need (`aer` for the local simulator, `ibm` for

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

@@ -91,7 +91,7 @@ $ shotgate run examples/bell-state/workflow.yaml
 The same run drops into a pipeline through the Markdown reporter (`--markdown`), rendered
 as a step summary or a PR comment:
 
-> ## shotgate: `bell-state` — ✅ passed
+> ## shotgate: `bell-state` (✅ passed)
 >
 > - Jobs: **1**, failed: **0**
 > - Assertions: **5**, failed: **0**
@@ -133,6 +133,10 @@ podman run --rm -e SHOTGATE_IBM_TOKEN \
   run examples/bell-state-hardware/workflow.yaml --backend ibm
 ```
 
+The same images are mirrored to Docker Hub if you prefer it: swap the registry prefix for
+`docker.io/coldqubit/shotgate` (tags `latest`, `latest-ibm`, and each version). GHCR is the
+canonical registry; the Docker Hub copy is a convenience mirror.
+
 ### Path B: pip (CLI and pytest plugin)
 
 Install the package with the backend extra you need (`aer` for the local simulator, `ibm` for

{shotgate-0.2.1 → shotgate-0.2.2}/SECURITY.md

@@ -15,7 +15,7 @@ acknowledge within 72 hours and to provide a remediation timeline after triage.
 
 ## Security model (what to attack / what we defend)
 
-- **Untrusted circuits.** Circuits are OpenQASM parsed by qiskit's QASM reader — not
+- **Untrusted circuits.** Circuits are OpenQASM parsed by qiskit's QASM reader, not
   `eval`'d Python. For circuits from untrusted sources, use the **VM isolation tier**
   (`infra/qemu`), which runs the workflow in an ephemeral KVM micro-VM.
 - **Secrets.** Provider tokens are read from environment variables / container `-e`

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

@@ -7,12 +7,12 @@
 | [Pipeline Schema](pipeline.md) | How shotgate gates a CI/CD pipeline; stage contract; exit codes. |
 | [Workflow Specification](workflow-spec.md) | The `shotgate.dev/v1alpha1` YAML schema, field by field. |
 | [Assertion Catalog](assertions.md) | The statistical oracles, with the math and threshold guidance. |
-| [Hardware Validation Plan](hardware-validation.md) | v0.2 runbook to validate the gates on a real IBM QPU. |
+| [Hardware Validation Plan](hardware-validation.md) | v0.2 milestone: runbook and measured `ibm_fez` baseline (2026-06-11). |
 | [Motivation](motivation.md) | The market/community gap shotgate fills, with sources. |
 | [ADRs](adr/) | Architecture Decision Records and their rationale. |
 | [Diagrams](diagrams/) | Mermaid sources for the architecture and pipeline diagrams. |
 
 Infrastructure docs live next to the code they describe:
 
-- [Terraform module](../infra/terraform/README.md) — quantum workflow as code.
-- [KVM/QEMU runner](../infra/qemu/README.md) — ephemeral VM isolation tier.
+- [Terraform module](../infra/terraform/README.md): quantum workflow as code.
+- [KVM/QEMU runner](../infra/qemu/README.md): ephemeral VM isolation tier.

{shotgate-0.2.1 → shotgate-0.2.2}/docs/adr/0001-record-architecture-decisions.md

@@ -6,8 +6,8 @@
 ## Context
 
 shotgate sits at an immature intersection (quantum × DevOps) where the "right" design
-is not yet settled by convention. Decisions — why statistical oracles, why containers,
-why a Terraform module instead of a provider — need to be legible to contributors and
+is not yet settled by convention. Decisions (why statistical oracles, why containers,
+why a Terraform module instead of a provider) need to be legible to contributors and
 to our future selves.
 
 ## Decision

{shotgate-0.2.1 → shotgate-0.2.2}/docs/adr/0002-statistical-validation-core.md

@@ -7,10 +7,10 @@
 
 Quantum programs are probabilistic; exact-equality assertions are either flaky or
 vacuous. The academic literature (χ²-as-oracle, QUTest, QuCheck, QUT) establishes the
-correct techniques — total variation distance, Hellinger fidelity, chi-square
-goodness-of-fit — but they live in research prototypes, not in production CI tooling.
+correct techniques (total variation distance, Hellinger fidelity, chi-square
+goodness-of-fit), but they live in research prototypes, not in production CI tooling.
 Meanwhile DevOps writers repeatedly note that quantum CI "lacks robust test
-frameworks" and needs "specialized validation… in CI/CD pipelines".
+frameworks" and needs "specialized validation... in CI/CD pipelines".
 
 We must also decide the dependency footprint. Pulling SciPy (for `chi2.sf`) and numpy
 into the core would make the metrics layer heavy and couple it to a scientific stack.

shotgate-0.2.2/docs/adr/0004-rename-qforge-to-shotgate.md

@@ -0,0 +1,35 @@
+# ADR-0004: Rename qforge to shotgate (and the workflow apiVersion with it)
+
+- **Status:** Accepted
+- **Date:** 2026-06-01
+
+## Context
+
+The project started on 2026-06-01 under the name `qforge`. Before any release was
+tagged, two problems surfaced: the name was already taken on the package indexes
+(PyPI and crates.io), and it raised a trademark concern on the VS Code marketplace.
+The name is load-bearing in more places than the repository title: the Python
+package, the command-line interface (CLI) program, the container image path, the
+environment variables, and the workflow schema's `apiVersion` literal
+(`qforge.dev/v1alpha1`) all embed it.
+
+## Decision
+
+Rename the project to **shotgate** everywhere the old name appeared: package
+`src/shotgate`, CLI program `shotgate`, image `ghcr.io/coldqubit/shotgate`,
+environment variable prefix `SHOTGATE_*`, and the workflow schema pin
+`apiVersion: shotgate.dev/v1alpha1`. The schema pin is a pydantic `Literal`, so a
+workflow declaring the old `qforge.dev/v1alpha1` fails schema validation rather
+than being silently accepted.
+
+## Consequences
+
+- **+** The name is unique on PyPI and the container registries, so the package and
+  image are installable under their own name with no squatting or trademark risk.
+- **+** It describes the product (gating on measurement shots) instead of a generic
+  "forge" metaphor.
+- **−** The `apiVersion` change is breaking for any pre-rename workflow file. The
+  impact was zero in practice: the rename landed on 2026-06-01 and the first tagged
+  release (`v0.1.0`) followed on 2026-06-10, so no published package, image, or tag
+  ever carried the old name and no external consumer existed to break.
+- The old name survives only in git history and in the `CHANGELOG.md` v0.1.0 notes.

shotgate-0.2.2/docs/adr/0005-license-apache-2-0.md

@@ -0,0 +1,48 @@
+# ADR-0005: License is Apache-2.0 (after MIT and an AGPL interlude)
+
+- **Status:** Accepted
+- **Date:** 2026-06-08
+
+## Context
+
+The project's license changed twice before the first release settled it:
+
+1. **MIT** at inception (2026-06-01).
+2. **AGPL-3.0-or-later** later the same day, chosen for the network copyleft:
+   distributing the tool, or running a modified version as a hosted service, would
+   have required releasing source.
+3. **Apache-2.0** on 2026-06-08, two days before the first tagged release.
+
+The week under AGPL exposed a conflict with the adoption model. shotgate's target
+user is a corporate continuous integration (CI) pipeline, and the quantum ecosystem
+it builds on (Qiskit, Qiskit Aer, Cirq, Mitiq) is Apache-2.0 licensed; a
+network-copyleft gate inside that stack invites legal review friction that a CI
+utility cannot justify, and the "hosted modified service" trigger is ambiguous for a
+tool whose whole purpose is to run inside other people's pipelines.
+
+Relicensing was legally clean at that date: every line of source had a single
+copyright holder (the maintainer), since the only third-party commits were
+Dependabot version-range bumps and none had landed before the relicense commit.
+
+## Decision
+
+License the project **Apache-2.0**: verbatim license text in `LICENSE`, the
+two-line SPDX header (`Apache-2.0`, `Copyright (C) 2026 coldqubit`) in all `src/`
+files (17 files at the time), the `Apache-2.0` expression and classifier in
+`pyproject.toml`, and the OCI license label in the `Containerfile`. Inbound
+contributions are accepted under a Developer Certificate of Origin (DCO) sign-off
+carrying the same Apache-2.0 terms (Apache-2.0 section 5), with no separate
+contributor license agreement.
+
+## Consequences
+
+- **+** Permissive adoption: use, modification, and redistribution for any purpose,
+  including commercial and closed-source, retaining the license and attribution
+  notices (Apache-2.0 sections 4(a) through 4(d)).
+- **+** An explicit patent grant (section 3), which MIT lacked.
+- **+** License-compatible with the Apache-2.0 quantum SDK stack it imports.
+- **−** The AGPL network-copyleft promise is removed, not replaced: a vendor can
+  ship a modified closed-source shotgate as a service.
+- **−** Practically irreversible: once external DCO-signed contributions land,
+  relicensing again would require every contributor's consent. This ADR therefore
+  also fixes the inbound policy (DCO, same license in and out).

shotgate-0.2.2/docs/adr/0006-hardware-oracle-policy.md

@@ -0,0 +1,48 @@
+# ADR-0006: chi_square is simulator-only; hardware gates use distance, fidelity, and structural oracles
+
+- **Status:** Accepted
+- **Date:** 2026-06-11
+
+## Context
+
+The v0.2 milestone ran the example gates on a real quantum processing unit (QPU)
+for the first time (`ibm_fez`, 156-qubit Heron r2, 4096 shots per job). Two facts
+came out of those runs:
+
+1. Simulator-tight thresholds (total variation distance (TVD) ≤ 0.03, Hellinger
+   fidelity ≥ 0.99, leakage ≤ 0.005) fail on a healthy device: the measured Bell
+   TVD was 0.1284 and the GHZ-3 TVD 0.1536.
+2. `chi_square` fails on hardware for a mechanical reason, not a tuning one. The
+   non-gating diagnostic Bell job (`d8l592rqv2lc738621eg`) returned statistic
+   1.5e17, dof 3, p-value 0.0000, while the four distance/structural oracles passed
+   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.
+
+## Decision
+
+1. **Hardware gates use the distance, fidelity, marginal, and structural oracles**
+   (`distribution_tvd`, `hellinger_fidelity`, `state_probability`,
+   `allowed_states`) with noise-aware thresholds (Bell: TVD ≤ 0.15, fidelity
+   ≥ 0.85, leakage ≤ 0.15; full table in `docs/hardware-validation.md` section 4),
+   encoded in the `examples/*-hardware` workflows.
+2. **`chi_square` stays simulator-only** until a gate can declare a noise-aware
+   expected distribution (a device error model with nonzero mass on the error
+   states), which is out of scope for v0.2.
+3. A **non-gating oracle-coverage diagnostic**
+   (`examples/bell-state-hardware-oracle-coverage`) keeps measuring all five
+   oracles on hardware so the exclusion stays evidence-based run over run.
+
+## Consequences
+
+- **+** The hardware gates pass a healthy device with measured margins of 0.0216
+  (Bell TVD, the tightest) to 0.1357 (Grover P(`11`)) while still bounding leakage
+  and fidelity, so they catch a broken circuit or mis-mapped qubits.
+- **−** The formal hypothesis test is unavailable on hardware, so hardware gating
+  loses the goodness-of-fit (GoF) guarantee and relies on distance bounds instead.
+- Revisit when an error-model expected distribution exists (candidate for the v0.3
+  error-mitigation work); the diagnostic's measurements will show when `chi_square`
+  becomes viable on devices.

{shotgate-0.2.1 → shotgate-0.2.2}/docs/architecture.md

@@ -1,19 +1,20 @@
 # Solution Architecture
 
-> Status: `v0.1` (alpha). This document describes the design, its rationale, and
-> the extension points that keep shotgate "minimal but scalable".
+> Status: `0.2.x` (alpha; oracles validated on `ibm_fez`, 2026-06-11). This document
+> describes the design, its rationale, and the extension points that keep shotgate
+> "minimal but scalable".
 
 ## 1. Problem statement
 
 Quantum programs are probabilistic. The same circuit, executed twice, returns
-different shot counts. Classical CI/CD — built on deterministic equality — has no
+different shot counts. Classical CI/CD, built on deterministic equality, has no
 native way to gate on this. Three concrete gaps follow:
 
 1. **No statistical quality gate.** Teams hand-roll ad-hoc `assert counts["00"] > N`
    checks that are either flaky or meaningless.
 2. **No "workflow as code".** There is no declarative, reviewable artifact that says
    *"this circuit, on this backend, must satisfy these statistical properties"*.
-3. **No IaC / isolation story.** Terraform/Helm can't describe quantum workloads, and
+3. **No Infrastructure-as-Code (IaC) / isolation story.** Terraform/Helm can't describe quantum workloads, and
    running untrusted circuits in CI lacks an isolation model.
 
 shotgate addresses all three with one composable tool.
@@ -22,7 +23,7 @@ shotgate addresses all three with one composable tool.
 
 | Principle | Consequence in the codebase |
 | --- | --- |
-| **Statistically correct by construction** | Oracles are χ², TVD, Hellinger fidelity — not equality. The χ² survival function is implemented from first principles ([`metrics.py`](../src/shotgate/validation/metrics.py)). |
+| **Statistically correct by construction** | Oracles are χ², total variation distance (TVD), Hellinger fidelity, not equality. The χ² survival function is implemented from first principles ([`metrics.py`](../src/shotgate/validation/metrics.py)). |
 | **Core is dependency-light** | The validation core imports only the standard library + pydantic. No quantum SDK is needed to parse a workflow or compute a metric. |
 | **Backends are lazy & pluggable** | Heavy SDKs (qiskit, braket) are imported only when a backend actually runs. New providers register a `"module:Class"` string. |
 | **Everything runs in a container** | The unit of execution is the shotgate image. The host needs only Podman (and optionally QEMU). |
@@ -33,13 +34,13 @@ shotgate addresses all three with one composable tool.
 
 ```mermaid
 flowchart TB
-    subgraph CoreLayer["Validation core — no quantum SDK required"]
+    subgraph CoreLayer["Validation core: no quantum SDK required"]
         config["config.py<br/>Workflow schema (pydantic)"]
         assertions["validation/assertions.py<br/>Oracle models + evaluate()"]
         metrics["validation/metrics.py<br/>TVD · Hellinger · χ² (incomplete gamma)"]
     end
 
-    subgraph ExecLayer["Execution layer — SDKs imported lazily"]
+    subgraph ExecLayer["Execution layer: SDKs imported lazily"]
         loader["circuits/loader.py<br/>OpenQASM → circuit"]
         registry["backends/registry.py<br/>provider → Backend"]
         base["backends/base.py<br/>Backend ABC + BackendResult"]
@@ -65,7 +66,7 @@ flowchart TB
 
 **Dependency direction is strictly downward.** `report` and `runner` depend on the
 core; the core never imports the execution layer. This is what lets the same wheel
-run a 30 MB metrics-only container and a full QPU job.
+run a 30 MB metrics-only container and a full quantum processing unit (QPU) job.
 
 ## 4. Execution data flow
 
@@ -116,11 +117,12 @@ flowchart LR
 | 2 | Rootless Podman, non-root image user | Shared/hardened CI runners. |
 | 3 | Ephemeral Fedora micro-VM (`infra/qemu`) | Untrusted circuits; VM-grade stage isolation. |
 
-See [ADR-0003](adr/0003-container-and-vm-isolation.md).
+See the Architecture Decision Record (ADR)
+[ADR-0003](adr/0003-container-and-vm-isolation.md).
 
 ## 6. Security model
 
-- **No executable circuits.** Circuits are OpenQASM, parsed by qiskit's QASM reader —
+- **No executable circuits.** Circuits are OpenQASM, parsed by qiskit's QASM reader,
   not `eval`'d Python.
 - **Strict schema.** Unknown fields are rejected, preventing silent misconfiguration.
 - **Secrets never touch disk.** Cloud tokens come from env vars / container `-e`; the
@@ -130,7 +132,7 @@ See [ADR-0003](adr/0003-container-and-vm-isolation.md).
 
 ## 7. Extension points (how it scales)
 
-| To add… | Do this | Touches the core? |
+| To add... | Do this | Touches the core? |
 | --- | --- | --- |
 | A new **assertion oracle** | Add a pydantic model with a unique `type` literal + `evaluate()`, append to the `Assertion` union and `ASSERTION_TYPES` | No core math beyond a new `metrics` fn |
 | A new **backend** | Implement `Backend`, register `"module:Class"` in the registry, add an optional extra | No |
@@ -140,7 +142,7 @@ See [ADR-0003](adr/0003-container-and-vm-isolation.md).
 Because the contract between layers is small (a `BackendResult` of counts, an
 `AssertionResult` of pass/fail+metrics), each layer evolves independently.
 
-## 8. Non-goals (v0.1)
+## 8. Non-goals (as of 0.2.x)
 
 - Circuit *synthesis* or optimization (that's the SDKs' job).
 - Full quantum-state tomography assertions (planned; counts-based oracles first).