foundry-testing-actor 0.1.0__tar.gz

foundry_testing_actor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+name: ci
+on: [push, pull_request]
+
+# NO CREDENTIAL. Nothing here authenticates to anything: no lab repo, no knowledge registry, no
+# PyPI upload, no image push. Everything this pipeline asserts about THIS package, it asserts from
+# source and from artifacts it built itself — the wheel it just built, and an image built from
+# that wheel rather than from a published one.
+#
+# It does reach the network for inputs: public base images and the npm package the engine drives.
+# That is fetching, not authenticating, and the distinction is the one that matters here — no
+# secret is available to this workflow, so nothing it runs can reach a real capability's repo.
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the test suite
+        run: uv run --extra dev pytest -q
+
+      - name: build
+        run: uv build
+
+      # ── the two gates a contract-shipping package runs against its own artifact ────────────
+      #
+      # The suite above proves the code works in a source checkout. Neither of these does — they
+      # prove the WHEEL works, which is a different claim and the one a consumer actually depends
+      # on. A schema left out of the build passes every test in tests/ and fails here.
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-testing-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-testing
+          /tmp/probe/bin/foundry-testing-actor show examples/ACME.PARTS.CAP.SUP.007.WID-testing \
+            --registry reg.example.com | tee /tmp/show.txt
+          grep -q 'reg.example.com/acme.parts/sup.007.wid/backend/tests:<version>' /tmp/show.txt
+          grep -q 'reg.example.com/acme.parts/sup.007.wid/backend:<version>' /tmp/show.txt
+
+      - name: the wheel must carry the actor's own cards
+        # The `-actor` suffix asserts a papeete-actor underneath, which lint-card can check
+        # (ADR-ECO-0022). The suite proves the cards are conformant in a source checkout; this
+        # proves they SHIPPED. A card folder left out of the build passes every test in tests/ and
+        # makes the name a claim the artifact cannot honour. `papeete-actor-synchronous-messaging`
+        # is already a runtime dependency, so its gate is in the probe venv with nothing to add.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_testing_actor import cards_path; print(cards_path())')"
+
+      - name: the wheel must carry the default runner
+        # A component that declares no `runner:` is built with the Dockerfile the wheel ships.
+        # A wheel without it lints every sidecar green and fails at the first publish — after a
+        # commit and a push have already landed.
+        run: |
+          /tmp/probe/bin/python -c 'from foundry_testing_actor import runner_path; p = runner_path() / "Dockerfile"; assert p.is_file(), p; print(p)'
+
+      - name: the gate must run
+        # A gate that cannot fail is not a gate. Lint a deliberately non-conformant sidecar with
+        # the INSTALLED wheel and require a non-zero exit.
+        run: |
+          if /tmp/probe/bin/foundry-testing-actor lint tests/fixtures/broken; then
+            echo "::error::lint accepted a non-conformant sidecar — the gate is not running"
+            exit 1
+          fi
+          echo "the gate refused a non-conformant sidecar, as it should"
+
+      - name: grounding renders a CLAUDE.md whose imports resolve
+        # The property the whole design rests on: an @-import naming a file that is not there is a
+        # session grounded in nothing, and it looks identical to one grounded correctly.
+        run: /tmp/probe/bin/python scripts/probe_grounding.py examples/ACME.PARTS.CAP.SUP.007.WID-testing
+
+  # ── the other half of what this package ships ─────────────────────────────────────────────────
+  #
+  # ADR-FTA-0001 (after ADR-FIA-0005): a use is a sidecar, and the image is what turns one into a
+  # running actor. The job above proves the WHEEL works. This one proves the claim a consumer actually depends on —
+  # that a folder containing one YAML file builds into an actor that boots and answers its doors.
+  # Nothing here reaches a registry: the image is built, run and thrown away in the runner.
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build the wheel this image will carry
+        # The image installs the wheel from dist/ rather than from PyPI, so that an image tagged
+        # <version> cannot contain some other build of <version> — see docker/Dockerfile.
+        run: uv build
+
+      - name: the base image
+        run: docker build -f docker/Dockerfile -t foundry-testing-actor:ci .
+
+      - name: the image and the wheel are one release
+        # Two artifacts, one version. An image whose wheel says something else is the failure this
+        # arrangement creates, so it is the one CI asserts.
+        run: |
+          wheel="$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')"
+          in_image="$(docker run --rm --entrypoint python foundry-testing-actor:ci \
+            -c 'from foundry_testing_actor import version; print(version())')"
+          echo "wheel=$wheel image=$in_image"
+          [ "$wheel" = "$in_image" ] || { echo "::error::image carries $in_image, wheel is $wheel"; exit 1; }
+
+      - name: a use is a sidecar
+        # The example folder holds exactly one file besides its Dockerfile. If this builds, the
+        # claim in the README is true of a real folder rather than of prose.
+        run: |
+          test "$(ls examples/ACME.PARTS.CAP.SUP.007.WID-testing | grep -cv '^Dockerfile$')" = "1"
+          docker build --build-arg ACTOR_IMAGE=foundry-testing-actor:ci \
+            -t use:ci examples/ACME.PARTS.CAP.SUP.007.WID-testing
+
+      - name: the rendered cards are what a caller is validated against
+        # Rendering is the construction that replaces the hand copy conformance.check was built to
+        # police. Assert it inside the image, against the cards the image actually runs.
+        run: |
+          docker run --rm use:ci foundry-testing-actor lint /actor
+
+      - name: it boots, and answers the doors its cards declare
+        # The credentials are deliberately junk. The engine refuses to construct without a
+        # GITHUB_TOKEN — which is itself worth having, and is why they are set rather than omitted
+        # — and no door is actually exercised here: a 400 means routed and refused the payload, a
+        # 404 would mean the route was never built.
+        run: |
+          docker run -d --name smoke -p 18080:8080 \
+            -e GITHUB_TOKEN=ci -e CLAUDE_CODE_OAUTH_TOKEN=ci use:ci
+          for _ in $(seq 1 30); do
+            curl -fsS -m 2 http://localhost:18080/health >/dev/null 2>&1 && break
+            sleep 1
+          done
+          curl -fsS -m 5 http://localhost:18080/health | grep -q ok
+          for door in test-task propose-acceptance; do
+            code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+              -H 'content-type: application/json' -d '{}' "http://localhost:18080/$door")"
+            [ "$code" = "400" ] || { echo "::error::POST /$door answered $code, expected 400 (routed, bad payload)"; exit 1; }
+          done
+          code="$(curl -sS -o /dev/null -w '%{http_code}' -m 5 -X POST \
+            -H 'content-type: application/json' -d '{}' http://localhost:18080/no-such-door)"
+          [ "$code" = "404" ] || { echo "::error::an undeclared door answered $code, expected 404"; exit 1; }
+          docker logs smoke | grep -q actor-started
+          docker rm -f smoke

foundry_testing_actor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,216 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+  # A REGISTRY ADDED AFTER A TAG WAS ALREADY CUT. The image job below publishes to two registries,
+  # and the second one was not always there. Running this workflow by hand backfills the image for
+  # a version whose wheel is already on PyPI — without inventing a version number whose only
+  # content is "the last release missed a registry".
+  #
+  # THE TAG IS AN INPUT, NOT THE REF THIS RUNS FROM. GitHub takes the workflow FILE from the ref it
+  # is dispatched on, and the tag needing a backfill is by definition older than the workflow that
+  # can do it — dispatching on that tag would run the very file that lacks this trigger. So run it
+  # from the default branch and name the tag here; the checkout below takes the CONTENT from the
+  # tag, and the version gate still refuses a tag that disagrees with the `pyproject.toml` beside
+  # it.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to publish an image for, e.g. v0.1.0"
+        required: true
+
+# PyPI Trusted Publishing (OIDC) — no token is stored anywhere. The one-time setup is a pending
+# publisher on pypi.org naming this repo and this workflow; after the first release it becomes a
+# normal publisher. See README.
+permissions:
+  id-token: write   # PyPI Trusted Publishing
+  contents: read
+  packages: write   # the image, to this repo's own container registry
+
+jobs:
+  publish:
+    # ONLY ON A TAG PUSH. A manual run exists to backfill an IMAGE (see `on:` above), and PyPI
+    # refuses a version it already holds — so re-uploading is not merely redundant, it fails, and
+    # would take the image job down with it.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: build
+        # No fetch step and no external token: the contract is committed here. A release depends
+        # on nothing but this checkout and PyPI.
+        run: uv build
+
+      - name: the wheel must carry its contract
+        run: |
+          uv venv /tmp/probe
+          uv pip install --python /tmp/probe/bin/python -q dist/*.whl
+          /tmp/probe/bin/foundry-testing-actor lint examples/ACME.PARTS.CAP.SUP.007.WID-testing
+
+      - name: the wheel must carry the actor's own cards
+        # Same reason as the line above, for the other half of what this package ships. The
+        # `-actor` suffix asserts a papeete-actor underneath (ADR-ECO-0022); a wheel published
+        # without its cards makes the name a claim the artifact cannot honour, and a published
+        # version is not something to discover that from.
+        run: |
+          /tmp/probe/bin/papeete-actor-synchronous-messaging lint-card \
+            "$(/tmp/probe/bin/python -c 'from foundry_testing_actor import cards_path; print(cards_path())')"
+
+      - name: the wheel must carry the default runner
+        # A component with no `runner:` is built from the Dockerfile the wheel ships; a published
+        # wheel without it fails at a use's first publish, after its commit and push have landed.
+        run: |
+          /tmp/probe/bin/python -c 'from foundry_testing_actor import runner_path; p = runner_path() / "Dockerfile"; assert p.is_file(), p; print(p)'
+
+      - name: grounding renders a CLAUDE.md whose imports resolve
+        # BEFORE the upload, not after. A wheel that ships without its schema, or whose grounding
+        # emits an @-import to a file it never wrote, produces sessions grounded in nothing that
+        # look identical to correct ones. That is not something to discover from a published
+        # version.
+        run: /tmp/probe/bin/python scripts/probe_grounding.py examples/ACME.PARTS.CAP.SUP.007.WID-testing
+
+      - name: publish to PyPI
+        run: uv publish --trusted-publishing always
+
+  # ── the image, from the same tag and the same checkout ────────────────────────────────────────
+  #
+  # TWO ARTIFACTS, ONE RELEASE (ADR-FTA-0001, after ADR-FIA-0005). A use pins an image; an
+  # embedder pins a wheel; both are this package at this version. A tag that produced one and not the other leaves a consumer
+  # unable to take the release at all — so this job builds the wheel again from the same checkout
+  # rather than installing the one just uploaded: the image must not depend on PyPI having already
+  # indexed it, and must not be able to pick up a different build of the same version.
+  #
+  # It runs AFTER the wheel is published, not beside it. A failed upload should not leave an image
+  # published for a version that does not exist on PyPI; the reverse — a wheel with the image still
+  # to come — is recoverable by re-running this job alone.
+  image:
+    needs: publish
+    # `needs` still orders this after the wheel on a tag push. On a manual backfill `publish` is
+    # skipped, and a skipped dependency skips its dependents too unless `always()` says otherwise —
+    # so the condition has to name both cases rather than relying on `needs` alone.
+    if: always() && (needs.publish.result == 'success' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Empty on a tag push, which is `checkout`'s own default — the ref that triggered the
+          # run. On a manual backfill it is the tag being republished, so every step below reads
+          # that tag's own tree rather than whatever the default branch has moved on to.
+          ref: ${{ inputs.tag }}
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: the version is the tag
+        # The tag is what a consumer writes in a FROM line. A tag that disagrees with
+        # pyproject.toml would publish an image whose own `version()` contradicts its name, which
+        # is exactly the confusion the CI gate above exists to prevent for the wheel. On a backfill
+        # this compares the named tag against the `pyproject.toml` checked out FROM that tag, so a
+        # typo in the input is refused rather than published under the wrong name.
+        id: version
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          tag="${TAG#v}"
+          declared="$(uv run --quiet python -c             'import tomllib,pathlib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          [ "$tag" = "$declared" ] || { echo "::error::tag $TAG does not match pyproject version $declared"; exit 1; }
+          echo "version=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: build
+        run: uv build
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: the image, tagged and latest
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          # `latest` FOLLOWS THE RELEASE STREAM, NOT A BACKFILL. A manual run exists to give an
+          # already-released version an image in a registry it missed; run against an older tag it
+          # would otherwise drag `latest` backwards onto it, silently, in whichever registry a
+          # consumer happens to pull from. The version tag is the whole point of a backfill —
+          # `latest` already names something newer, and stays there.
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          image="ghcr.io/${{ github.repository }}"
+          docker build -f docker/Dockerfile -t "$image:$VERSION" -t "$image:latest" .
+          docker push "$image:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then docker push "$image:latest"; fi
+
+      # ── the product's own registry ────────────────────────────────────────────────────────────
+      #
+      # TWO REGISTRIES, ONE IMAGE. GHCR is where this package publishes; a product that RUNS uses
+      # of it pulls from its own registry, which its cluster already authenticates to and which a
+      # `FROM` line inside that cluster's builder can reach without a second credential. The base
+      # image has to exist in both, because the two are reached by different things: an embedder
+      # writing a Dockerfile reads the README and pins GHCR, while a use built by an in-cluster
+      # builder resolves its `FROM` against the registry that builder has a push token for.
+      #
+      # THE SAME IMAGE, NOT ANOTHER BUILD. `docker tag` re-points the build the step above already
+      # pushed, so both registries hold one digest. Building a second time would let them diverge —
+      # a base-image refresh between two steps of one job is enough — and nothing downstream would
+      # ever notice that `:0.1.0` meant two different things depending on where you pulled it.
+      #
+      # ONE VARIABLE NAMES THE WHOLE TARGET. `vars.PRODUCT_IMAGE` is the full repository path, e.g.
+      # `<name>.azurecr.io/<product>/foundry-testing-actor`; the login server is its first
+      # segment. This package is generic across capabilities and names no product of its own — the
+      # same rule `tests/test_portability.py` enforces over `src/` — so the product that hosts a
+      # registry names itself in a repository variable rather than in this file.
+      #
+      # UNSET IS A VALID STATE, AND IT SAYS SO. A fork, or this repo before its credentials were
+      # added, publishes to GHCR alone; that is a `::notice`, not a failure. Configured-but-broken
+      # IS a failure — the push below is not best-effort, because an image the product's cluster
+      # cannot pull is the whole reason this block exists.
+      - name: is a product registry configured?
+        id: product
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+        run: |
+          if [ -z "$PRODUCT_IMAGE" ]; then
+            echo "::notice::PRODUCT_IMAGE is unset — publishing to GHCR only"
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          case "$PRODUCT_IMAGE" in
+            */*/*) : ;;
+            *) echo "::error::PRODUCT_IMAGE must be <registry>/<path>/<repository>, got $PRODUCT_IMAGE"; exit 1 ;;
+          esac
+          echo "server=${PRODUCT_IMAGE%%/*}" >> "$GITHUB_OUTPUT"
+          echo "configured=true" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/login-action@v3
+        if: steps.product.outputs.configured == 'true'
+        with:
+          registry: ${{ steps.product.outputs.server }}
+          username: ${{ secrets.ACR_PUSH_USERNAME }}
+          password: ${{ secrets.ACR_PUSH_PASSWORD }}
+
+      - name: the same image, in the product's registry
+        if: steps.product.outputs.configured == 'true'
+        env:
+          PRODUCT_IMAGE: ${{ vars.PRODUCT_IMAGE }}
+          VERSION: ${{ steps.version.outputs.version }}
+          MOVE_LATEST: ${{ github.event_name == 'push' }}
+        run: |
+          ghcr="ghcr.io/${{ github.repository }}"
+          docker tag "$ghcr:$VERSION" "$PRODUCT_IMAGE:$VERSION"
+          docker push "$PRODUCT_IMAGE:$VERSION"
+          if [ "$MOVE_LATEST" = "true" ]; then
+            docker tag "$ghcr:latest" "$PRODUCT_IMAGE:latest"
+            docker push "$PRODUCT_IMAGE:latest"
+          fi
+
+      - name: a use built on it is still an actor
+        # BEFORE the image is something anyone can pin — the same reason the grounding probe runs
+        # before the upload above. An image that builds but produces a use that does not conform is
+        # not something to discover from a published tag.
+        run: |
+          docker build --build-arg ACTOR_IMAGE=ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }} \
+            -t use:release examples/ACME.PARTS.CAP.SUP.007.WID-testing
+          docker run --rm use:release foundry-testing-actor lint /actor

foundry_testing_actor-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+.serena/

foundry_testing_actor-0.1.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this
+repository.
+
+## What this is
+
+`foundry-testing-actor` runs a headless Claude Code session that authors black-box tests for one
+capability's increment in that capability's own testing repo, then commits, pushes and publishes a
+runnable test image. Before anything is built it answers `propose-acceptance`, its half of the
+three amigos round. It is the **machinery** — it carries no capability of its own. The capability
+arrives in a sidecar (`actor-agentic-context.yaml`, contract
+`foundry-testing-actor/agentic-context/v1`) that the consuming repo writes.
+
+Ported from one capability's hand-written testing actor, with `foundry-implementation-actor`
+(FIA) as the template. See `adr/ADR-FTA-0001-*.md`.
+
+## Commands
+
+```bash
+uv run --extra dev pytest -q                                    # full suite (what CI runs)
+uv run --extra dev pytest -q tests/test_config.py               # one file
+uv run --extra dev pytest -q tests/test_config.py::test_name    # one test
+uv build                                                        # sdist/wheel (hatchling)
+uv run foundry-testing-actor lint <folder>                      # validate a sidecar
+uv run foundry-testing-actor show <folder> --registry r         # every derived rendering
+```
+
+There is no separate lint/format command configured in this repo.
+
+## Architecture
+
+Modules under `src/foundry_testing_actor/`:
+
+- **`config.py`** — `CapabilityConfig`. Loads the sidecar and derives **every** rendering of the
+  capability id from `capability` and `source_repo` (plus `implementation_repo`, derived unless
+  declared). Carries `lint()`, `Report`, `cards_path()` and `runner_path()`.
+- **`grounding.py`** — copied from FIA: runs each `ground_in` `fetch:`, writes envelopes inside
+  the clone, renders the `CLAUDE.md` that `@`-imports the eager ones.
+- **`engine.py`** — `ClaudeCodeTesterEngine`. One engine, two doors, dispatched on the door id.
+  `propose-acceptance`: read-only clones (testing repo + implementation DEFAULT branch), `Read,
+  Glob,Grep`, small budget, projected JSON reply. `test-task`: rw testing clone on `test/<id>`,
+  implementation clone on `impl/<id>` for image recomputation only, full tool session. Never
+  commits.
+- **`handler.py`** — `make_test_task(config)`. Containment, commit, push, publish. Never opens a PR.
+- **`correlation.py`** — the two ids and the step vocabulary; byte-identical to FIA's.
+- **`conformance.py`**, **`instance.py`**, **`serve.py`**, **`cli.py`** — copied from FIA, renamed.
+
+Beside them, three folders shipped in the wheel: `schemas/` (the sidecar contract), `cards/` (the
+actor's four cards), and `runner/` (the default test-runner Dockerfile a component without
+`runner:` is built with).
+
+## Core invariants that any change must preserve
+
+- **The proposal is never derived from the build.** `propose-acceptance` clones the implementation
+  repo's default branch and never checks out `impl/<task_id>`; `test-task` checks it out but never
+  shows it to the session. `tests/test_engine.py` pins both. This is ADR-FIA-0004's "before or
+  after", and the whole value of the round.
+- **A door that cannot write beats a door asked not to.** `PROPOSE_TOOLS` carries no Write, Edit or
+  Bash. The propose door registers no handler.
+- **The wire contract is shared with two other packages.** Door ids, message names and fields are
+  fixed by the three-amigos contract FIA and the orchestration actor also implement. Do not rename
+  them; `tests/test_cards.py` pins the shapes.
+- **A use's cards are rendered, and hand copies drift.** `conformance.check` compares the DERIVED
+  wire contract, never prose. CI runs `lint-card` against the built wheel.
+- **No capability literal, no knowledge tool name, ever.** `tests/test_portability.py` greps `src/`
+  for both. A knowledge source is a `ground_in` entry, never a change here.
+- **The image refs are three-way contracts.** `<registry>/<capability_path>/<component>/tests:<v>`
+  (published) and `<registry>/<capability_path>/<component>:<v>` (recomputed, must match what the
+  implementation actor published). `config.test_image_ref` / `config.image_ref` output or nothing.
+- **The write boundary is stated once**, as `components[].tests`. Resolution is longest-prefix.
+- **The propose reply is projected** onto the completion message's fields. The framework leaves a
+  single-outcome completion schema open, so a session's stray keys would otherwise reach the
+  orchestrating actor dressed as part of a shared contract.
+- **The observability record schema is the contract; step names are not.** Every emitted log line
+  is budgeted to 64 KB.
+- **The clone is full, never `--depth 1`** — `papeete_version.compute()` needs tags reachable.
+- **The generated `CLAUDE.md` appends** to one the repo already commits. Never overwrite.
+- **The image is one build in two registries** (FIA's ADR-FIA-0006, copied). Never a second
+  `docker build`, never a hardcoded product registry.
+- **Never set `ANTHROPIC_API_KEY` in a container running this.**
+
+## Scope discipline
+
+Generic across **capabilities**, not across actor *kinds*. The machinery shared with FIA is a
+**copy by decision**, not a shared kit (ADR-FTA-0001): do not extract a common package, and do not
+change FIA from here. No hooks, no base classes, no strategy objects for a hypothetical consumer.
+
+Design rationale lives in `adr/`. Add a new ADR (copy `adr/template.md`) for any decision of
+similar weight rather than only writing it into code comments.
+
+## Releasing
+
+Tag-triggered (`v*`) via `.github/workflows/release.yml`: PyPI through Trusted Publishing, the image
+to GHCR and, when `vars.PRODUCT_IMAGE` names one, to a product registry too. A manual run takes a
+tag as input to backfill an image; it skips PyPI and does not move `latest`. `ci.yml` runs the
+suite, the wheel gates (contract, cards, the gate must fail, grounding probe), and builds + boots
+the example use.