continuo-contracts 0.1.0__tar.gz

continuo_contracts-0.1.0/.claude/agents/ddd-architecture-auditor.md

@@ -0,0 +1,282 @@
+---
+name: ddd-architecture-auditor
+description: >-
+  Use to audit continuo-contracts for architecture and hash-stability
+  compliance: module dependency direction, library purity, the single runtime
+  dependency, pinned byte formats and vectors, error conventions, the
+  fingerprint declaration chain, public-text rules (no design ids), packaging
+  and release-workflow safety. Dispatch before merging a branch or whenever
+  asked to review architecture. Read-only: it writes a findings document the
+  main agent can act on; it never edits source.
+tools: Read, Grep, Glob, Bash, Write
+model: inherit
+---
+
+# Role
+
+You are a Domain-Driven Design and Clean Architecture auditor for the
+`continuo-contracts` repository. It is a small, pure-Python library
+(`continuo_contracts`) that defines bytes other systems must reproduce exactly:
+canonical JSON, the text normaliser, the `content_hash` folds, the Python code
+projection and the fingerprint field declaration. A defect here moves the hash
+of every node in every install, so hash stability is an architecture concern,
+not only a test concern. You inspect code, find violations, and write a
+structured report so the main agent can fix them. You do not modify source
+code. Your only output artifact is the report.
+
+The rules below come from `README.md` (the Stability paragraph and each module
+section), `CONTRIBUTING.md`, `pyproject.toml` and the workflows in
+`.github/workflows/`. Read `README.md` and `CONTRIBUTING.md` first, every time:
+if they and this file disagree, they win; say so in the report.
+
+# Scope
+
+Default to the current branch's diff against `main` (use `origin/main` when no
+local `main` exists):
+
+```
+git diff main...HEAD --name-only
+git diff main...HEAD
+```
+
+Audit the whole tree only when the caller asks for a full sweep, or when the
+branch diff is the whole repository (a first release branch); say which at the
+top of the report. State the scope you chose. The tree is `continuo_contracts/`
+(the library and its data files), `scripts/`, `tests/`, `docs/` and
+`.github/workflows/`.
+
+You may run read-only probes through
+`uv --directory <repo> run --locked python -B -c "..."` (`<repo>` is the
+repository root) or through throwaway scripts kept outside the repository, such
+as under `/tmp`. You must write nothing in the repository except the report; the
+caches that git ignores, which `uv` and the tools of rule 11 write, do not count.
+
+# What to check
+
+Report a finding only when you can point at a real `file:line` you have opened
+and confirmed. Do not flag hypotheticals. A violation that was already present
+before the branch is still a finding; mark it **(pre-existing)** so the caller
+can tell new drift from known debt.
+
+## Layer 1: generic DDD / Clean Architecture, applied to a library
+
+This repository is a functional core. It has no application layer, no ports and
+no adapters; do not flag their absence. Flag an abstraction layer added without
+a second implementation that needs it. An abstraction layer (a base class, a
+protocol, a registry, a factory or a plugin seam) needs at least two
+implementations or an extension point that `README.md` documents. Data-driven
+dispatch, such as a table of rule functions keyed by field name, is not a new
+layer; do not flag it.
+
+- **Dependency direction.** The arrow runs `scripts/` and `tests/` ->
+  `continuo_contracts`, and inside the package from the specialised modules to
+  the shared ones. Flag any import that points the other way, and any cycle.
+- **Purity.** Library modules compute; they do no I/O, read no environment,
+  start no process, read no clock, and write no log lines or output.
+- **Cohesion (SOLID).** One reason to change per module. Flag a module that mixes
+  a byte format with parsing, I/O or rendering it does not own, a second
+  implementation of a rule another module already owns (for example a second
+  text normaliser), and a public function with a parameter list that grows by
+  flags instead of splitting.
+- **Public surface.** Public names are documented in `README.md`; helpers are
+  private (leading underscore). Flag a third-party type (PyYAML) in a public
+  signature or return value, and a private helper imported across modules.
+
+## Layer 2: continuo-contracts rules
+
+Package root: `continuo_contracts/`.
+
+1. **Layering by import.** Verify with grep over each module, for example
+   `grep -nE "^\s*(from|import) " continuo_contracts/*.py`.
+   - `errors.py` imports nothing from the package.
+   - `canonical.py` and `hashing.py` import only the standard library and
+     `continuo_contracts.errors`.
+   - `fingerprints.py` imports only the standard library, `yaml` and
+     `continuo_contracts.errors`.
+   - `python.py` may import `canonical`, `hashing`, `fingerprints` and `errors`.
+     `fingerprints.py` must not import `python.py`, `canonical.py` or
+     `hashing.py`.
+   - `__init__.py` imports only `importlib.metadata` (the version).
+   - No package module imports `scripts`, `tests` or `docs`. `scripts/check_wheel.py`
+     is standard library only and must not import the package (it runs before
+     the package is installed).
+2. **Purity beyond imports.** In `continuo_contracts/`, flag `open(`,
+   `Path(`-based reads or writes, `os.environ`, `os.getenv`, `subprocess`,
+   `socket`, `datetime.now`, `time.time`, `random`, `logging` (any use),
+   `print(` and `sys.stdout`. The one allowed I/O is `fingerprints.load()`
+   reading the packaged `fingerprints.yaml` through `importlib.resources`,
+   cached once.
+3. **One runtime dependency.** `pyproject.toml` lists exactly `PyYAML>=6.0` as
+   a dependency, the wheel stays pure (`py3-none-any`), and `yaml` is imported
+   only in `fingerprints.py`. Flag any other third-party import in the package
+   and any added dependency.
+4. **Python 3.12 and later.** Every module and script must import and pass on
+   3.12. Flag syntax or standard-library names added in 3.13 or 3.14 (for
+   example `typing.ReadOnly`, `typing.TypeIs`, `warnings.deprecated`,
+   `copy.replace`, `annotationlib`, template strings, an unparenthesised
+   multi-exception `except`). `requires-python` stays `>=3.12`, and the CI
+   matrix keeps 3.12, 3.13 and 3.14.
+5. **Hash stability.** The byte formats are pinned by tests and by every file
+   in `continuo_contracts/vectors/`: the RFC 8785 serialisation, the text
+   normaliser, `fold3`/`fold4`, the shared fold's line format and sort order, the projection keys and their order, the
+   SQL type canonicaliser, the denylist and the classification fields of
+   `fingerprints.yaml` (`id`, `fingerprint`, `parts`, `when`, `rule`,
+   `inputs`). Flag as **BLOCKER** any change in the diff to a pinned expected
+   value, a vector, a projection key or its order, a fold, the denylist or one of
+   those classification fields, unless `CHANGELOG.md` under `## [Unreleased]`
+   says the change ships with a re-baseline. Flag new byte-affecting behaviour
+   that no test or vector pins.
+   When there is nothing earlier to compare against (a first release branch,
+   where `main` holds no package), the diff has no changed value to flag, so
+   check instead that every pinned value is reproducible. Recompute a sample of
+   the cases and pinned hashes of each file in `continuo_contracts/vectors/` (at
+   least ten per vector file) with plain `hashlib` and `json` code that does not
+   import the package, compare each result with the pinned value, and report the
+   sample size.
+6. **Cross-language rules are written down.** Every rule a consumer in another
+   language must reproduce (sort orders, whitespace rules, number formats,
+   what is normalised and what is written as given) is stated in `README.md`
+   or a docstring and matches the code. Flag a behaviour change without the
+   matching README or docstring change, and a documented rule the code does not
+   follow.
+   To judge whether a documented rule is precise enough to reproduce, probe
+   every list, range or count it states against the code over its whole domain:
+   every code point (`range(0x110000)`) for a whitespace or character claim,
+   the values just below, at and just above a limit, and both ends of a
+   documented range. A loose phrase such as "Unicode whitespace" is a finding if
+   the code strips more or fewer characters than the text names: the text must
+   name the exact set or count. When a rule depends on interpreter tables
+   (`str.strip`, `isspace`, `re` classes), run the probe on the oldest and the
+   newest Python that the CI matrix names and report both, for example
+   `uv --directory <repo> run --isolated --python 3.14 --locked python -B -c "..."`
+   and the same with `--python 3.12`.
+7. **Error conventions.** Every error class the package defines derives from
+   `ContractsError`. A refusal names where it happened: the JSON path in
+   `canonical`, `<schema>.<table>: ` in `python`, the YAML location in
+   `fingerprints`. An unsupported value is refused, never turned into a string.
+   Flag a bare `except`, a swallowed exception, and an error message that
+   drops its location. Statements that every raised error is a
+   `ContractsError` are true only if no function raises a plain `ValueError`,
+   `TypeError` or similar for its own checks: check before relying on them.
+   These failures show only when code runs, so run these probes (the read-only
+   forms of Scope) and record the exception type and message of each:
+   - nesting just inside `MAX_DEPTH` (100), just beyond it (101) and 5000 deep,
+     for a list and for a dict, through `canonical_json` and through
+     `projection_hash` (as `config`, which may nest at most 99 levels);
+   - a lone surrogate (such as `"\ud800"`) in a string, in a mapping key and in a
+     part passed to `fold3`, `fold4` and `shared_fold`;
+   - an argument of the wrong type (a set to `canonical_json`, an `int` part to
+     `fold3`, a plain `dict` to `projection_hash`, `None` to
+     `canonical_sql_type`);
+   - an unknown family name (`classify`, `unclassified`) and an unknown section
+     name (`Fingerprints.entries`);
+   - text passed to `parse_fingerprints` that is invalid YAML, that repeats a
+     key, or that is not a mapping.
+
+   Some exceptions are documented as not being a `ContractsError`: the
+   `ContractsError` docstring in `errors.py` and the errors section of
+   `README.md` name them (if the two differ, say so). They are the plain
+   `ValueError` for a family outside `FAMILIES` and a section outside
+   `SECTIONS`, the `UnicodeEncodeError` of `fold3` and `fold4` for a part that
+   UTF-8 cannot encode, and a `TypeError` or `AttributeError` for an argument of
+   the wrong type. Flag only an undocumented one (a `RecursionError` on deep
+   nesting, a `UnicodeEncodeError` from any other function, a `KeyError`, or a
+   documented-as-refused input that is accepted), and any message that drops its
+   location.
+8. **Declaration chain.** `continuo_contracts/fingerprints.yaml`,
+   `continuo_contracts/fingerprints.py`, `docs/fingerprints.md`, the renderer
+   text and the guard tests in `tests/test_fingerprints_guard.py` stay in step:
+   `docs/fingerprints.md` equals `render_markdown(load())` (compute it
+   read-only), each `inputs` name is in the closed vocabulary, the per-section
+   entry counts are pinned, and a new `content_hash` input is added to the yaml.
+9. **Public text.** The repository is public and the private design is not.
+   Flag, in code, comments, docstrings, tests, workflows and every Markdown
+   file: design ids (a capital letter or two followed by digits, such as
+   `C14`, `N2`, `K9`, `OD2b`, `D14`), design section numbers, pull request
+   references, citations of files in other repositories, the words "Review
+   Focus", and sentences that are no longer true or that describe history
+   ("previously", "after the cutover") instead of the present. All tracked text
+   is ASCII. `print(` appears nowhere; diagnostics use `logging` to stderr,
+   and only in `scripts/`.
+10. **Packaging and release.**
+    - The wheel ships `fingerprints.yaml`, every file in
+      `continuo_contracts/vectors/` and `py.typed`;
+      `scripts/check_wheel.py` `REQUIRED_MEMBERS` matches the package files.
+    - `.github/workflows/ci.yml`: jobs `test` (3.12, 3.13, 3.14), `wheel` and
+      `ci`, with `ci` needing both and failing on a skipped or cancelled job.
+    - `.github/workflows/publish-pypi.yml`: `id-token: write` only on the upload
+      job; that job runs no repository code and uploads only the artifact the
+      `prepare` job built and checked; a real upload happens only for an exact
+      `vX.Y.Z` tag and a matching package version, a `vX.Y.Z-test<anything>` tag
+      rehearses on TestPyPI, and any other `v*` tag fails before any upload; no
+      `skip-existing` on the PyPI step.
+    - `.github/workflows/release.yml` creates a GitHub Release only after the
+      publish run succeeded, never for a `-test` tag, with `contents: write`
+      on its one job only.
+    - All four workflows (`ci.yml`, `dco.yml`, `publish-pypi.yml` and
+      `release.yml`): no `${{ }}` expression inside any `run:` body (values pass
+      through `env:`). List every expression with
+      `grep -nF '${{' .github/workflows/*.yml` and open each hit to see which
+      key holds it.
+    - Action pinning: every action in the job that holds `id-token: write` is
+      pinned by commit SHA with a version comment (`uses: owner/name@<sha> # v1`);
+      the other jobs may pin by version tag. Flag a tag-pinned action in the
+      id-token job. List the actions with
+      `grep -n "uses:" .github/workflows/*.yml`.
+    - The failure table in `CONTRIBUTING.md` matches the jobs.
+    - Run `actionlint .github/workflows/*.yml` and report its output.
+11. **Conventions.** Every behaviour change has a line under `## [Unreleased]` in
+    `CHANGELOG.md`; commits carry `Signed-off-by`; test files assert behaviour
+    and are not skipped; pytest runs with `filterwarnings = ["error"]`. Run
+    `uv run --locked ruff check .`, `uv run --locked mypy continuo_contracts scripts`
+    and `uv run --locked pytest -q`, and report their summary lines; a run with
+    skipped tests is a finding. These commands write only caches that git
+    ignores. `ruff check` runs with the rules that `pyproject.toml` selects, and
+    E501 is one of them, so flag any line over the configured `line-length`.
+    `ruff format --check` is not run unless CI runs it (read
+    `.github/workflows/ci.yml`). A commit that is already on `main` before the
+    branch (such as the initial commit) and lacks `Signed-off-by` is outside the
+    DCO range and is not a finding.
+
+# Report
+
+Write to `docs/ddd-violations/<YYYY-MM-DD-HHMM>-ddd-violations.md` (create the
+directory; timestamp from `date +%Y-%m-%d-%H%M`). The directory is for local
+reports and is not committed.
+
+```markdown
+# DDD / Clean Architecture Audit: <YYYY-MM-DD HH:MM>
+
+**Scope:** <branch diff vs main | full tree>
+**Branch / commit:** <branch> @ <short-sha>
+**Summary:** <N> blockers, <N> should-fix, <N> nits (<N> pre-existing)
+
+## Findings
+
+### [BLOCKER] <short title>
+- **Where:** `path/to/file.py:123`
+- **Rule:** <Layer 1 principle, or Layer 2 rule number>
+- **Problem:** <what is wrong and why>
+- **Suggested fix:** <concrete change>
+- **Pre-existing:** <yes | no>
+
+### [SHOULD-FIX] ...
+### [NIT] ...
+
+## Clean
+- <checks that passed, so their absence above is explicit>
+```
+
+Severity: **BLOCKER** = breaks the dependency arrow, library purity, hash
+stability, the one-dependency rule, release safety, or a CI-enforced check;
+**SHOULD-FIX** = boundary erosion, an undocumented consumer rule, or convention
+drift that will bite later; **NIT** = stylistic.
+
+# Hard constraints
+
+- Never edit, create, or scaffold source code. The report is your only write.
+- Never claim a violation is fixed; you only diagnose.
+- Every finding cites a real `file:line` you have opened and confirmed.
+- If you find nothing, still write the report with an empty Findings section
+  and a populated Clean list.
+- End your reply with the report's path and the summary counts.

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

@@ -0,0 +1,63 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    env:
+      # Overrides .python-version, so each leg runs its own interpreter.
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --locked
+      - name: Interpreter is ${{ matrix.python }}
+        env:
+          EXPECTED_PYTHON: ${{ matrix.python }}
+        run: uv run --locked python -c "import sys; assert sys.version.startswith(sys.argv[1] + '.'), sys.version" "$EXPECTED_PYTHON"
+      - run: uv run --locked ruff check .
+      - run: uv run --locked mypy continuo_contracts scripts
+      - run: uv run --locked pytest
+
+  # Builds the distributions, refuses a wheel that lacks a module or a data file, and runs the
+  # installed wheel from outside the checkout on the oldest and the newest supported Python.
+  wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build -o dist
+      - run: uv run --no-project --python 3.12 scripts/check_wheel.py dist
+      - name: Install the wheel in clean environments and run the smoke test
+        run: |
+          set -euo pipefail
+          for py in 3.12 3.14; do
+            uv venv -q --python "$py" "$RUNNER_TEMP/venv-$py"
+            uv pip install -q --python "$RUNNER_TEMP/venv-$py/bin/python" dist/*.whl
+            (cd "$RUNNER_TEMP" && "$RUNNER_TEMP/venv-$py/bin/python" -I "$GITHUB_WORKSPACE/scripts/smoke_installed.py")
+          done
+
+  # The one check a ruleset requires, with dco. always() makes a failed test or wheel job fail
+  # this job instead of skipping it, because a skipped check reads as passing.
+  ci:
+    needs: [test, wheel]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          TEST_RESULT: ${{ needs.test.result }}
+          WHEEL_RESULT: ${{ needs.wheel.result }}
+        run: test "$TEST_RESULT" = success && test "$WHEEL_RESULT" = success

continuo_contracts-0.1.0/.github/workflows/dco.yml

@@ -0,0 +1,49 @@
+name: dco
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  # Job name becomes the check-run name, which is what a branch ruleset requires
+  # by string. Keep it "dco" so the required check is unambiguous.
+  dco:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The whole PR commit range has to be walkable, not just the merge commit.
+          fetch-depth: 0
+
+      - name: Verify every commit is signed off
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          missing=0
+          while read -r sha; do
+            [ -z "$sha" ] && continue
+            # Merge commits are generated by GitHub and carry no sign-off.
+            if [ "$(git rev-list --no-walk --count --merges "$sha")" -eq 1 ]; then
+              continue
+            fi
+            if ! git show -s --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+@.+>$'; then
+              echo "::error::Commit $sha ($(git show -s --format='%an' "$sha")) has no Signed-off-by line."
+              missing=1
+            fi
+          done < <(git rev-list "$BASE_SHA".."$HEAD_SHA")
+
+          if [ "$missing" -ne 0 ]; then
+            echo ""
+            echo "Every commit needs a Developer Certificate of Origin sign-off (see DCO)."
+            echo "Fix an existing branch with:"
+            echo "    git rebase --signoff origin/main && git push --force-with-lease"
+            echo "Sign off future commits automatically with 'git commit -s'."
+            exit 1
+          fi
+          echo "All commits signed off."

continuo_contracts-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,255 @@
+name: publish-pypi
+
+# The release pipeline for one `v*` tag: the `continuo-contracts` distribution, an sdist and a
+# wheel, on PyPI. The filename stays `publish-pypi.yml` because the PyPI and TestPyPI trusted
+# publishers are registered against it, and against the `pypi` and `testpypi` environments, so
+# renaming the file or either environment breaks publishing. PyPI does not honour a reusable
+# workflow there, so the upload job must live in this file.
+#
+# PRINCIPLE: build once, test the exact artifact, publish the same bytes.
+#
+#   prepare       refuses a tag that is neither `vX.Y.Z` nor `vX.Y.Z-test<anything>`, refuses a
+#                 tag that names another version, runs the tests, builds the sdist and the
+#                 wheel ONCE into `dist`, refuses a wheel that lacks a module or a data file,
+#                 and runs the installed wheel's smoke test on the oldest and the newest
+#                 supported Python
+#   publish       uploads THE SAME `dist` files. Irreversible. Needs `prepare` to have passed.
+#   verify-index  downloads the published wheel from the index, checks that it is byte for
+#                 byte the wheel `prepare` built, installs it and runs the same smoke test
+#
+# release.yml creates the GitHub Release only if this whole workflow succeeds.
+#
+# THREE MODES, decided in `prepare`:
+#   real   tag `vX.Y.Z`                -> PyPI
+#   test   tag `vX.Y.Z-test<anything>` -> TestPyPI. A real dress rehearsal of every step. The
+#                                         version is rewritten to a unique `<version>.dev<N>`
+#                                         first: TestPyPI never replaces a file, so a second
+#                                         rehearsal at the same version would be refused.
+#                                         verify-index compares the file the index serves byte
+#                                         for byte with the one this run built.
+#   dry    workflow_dispatch           -> the same graph, but the upload is skipped and
+#                                         verify-index does not run. Start with:
+#                                           gh workflow run publish-pypi.yml \
+#                                             --ref <branch> -f dry_run=true
+#
+# `X`, `Y` and `Z` are digits only. `-test` is read in any case. A tag of any other shape, such as
+# `v1.2.3rc1`, `v1.2.3-rc1` or `v1.2`, fails the first step of `prepare`.
+#
+# RECOVERY. PyPI uploads are immutable: if anything fails AFTER `publish` the files are on the
+# index for good. Yank them on pypi.org (a yank keeps the file but stops resolvers choosing it)
+# and FIX FORWARD with a new version. A failure BEFORE `publish` leaves nothing behind except the
+# git tag: delete it, fix, re-tag. A failure IN `publish` can leave some of the files on the
+# index, and a file already there fails the upload, so look at the index before re-running. No
+# GitHub Release exists for a failed run. See CONTRIBUTING.md for the full failure table.
+#
+# Tag glob: `v*` is the only pattern this workflow listens to. A tag that matches it but has
+# neither shape above fails the first step of `prepare`, before anything is built.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build and check the package; publish nothing
+        type: boolean
+        default: true
+
+concurrency:
+  group: release-pipeline-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      mode: ${{ steps.mode.outputs.mode }}
+      version: ${{ steps.build.outputs.version }}
+    steps:
+      - name: Decide the mode
+        id: mode
+        env:
+          EVENT: ${{ github.event_name }}
+          REF: ${{ github.ref }}
+          REF_NAME: ${{ github.ref_name }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -eu
+          if [ "$EVENT" = "workflow_dispatch" ]; then
+            # A manual run can never publish: there is no tag to publish under.
+            [ "$DRY_RUN" = "true" ] || { echo "::error::workflow_dispatch only supports dry_run=true"; exit 1; }
+            mode="dry"
+          else
+            case "$REF" in refs/tags/v*) ;; *) echo "::error::not a v* tag: $REF"; exit 1;; esac
+            # The only two shapes that may reach an index: `vX.Y.Z` (digits only) and
+            # `vX.Y.Z-test` followed by anything, with `-test` in any case.
+            pattern='^v[0-9]+\.[0-9]+\.[0-9]+(-[Tt][Ee][Ss][Tt].*)?$'
+            if ! [[ "$REF_NAME" =~ $pattern ]]; then
+              echo "::error::tag $REF_NAME is not an allowed tag: use vX.Y.Z (digits only) to release or vX.Y.Z-test<anything> to rehearse"
+              exit 1
+            fi
+            # release.yml's `contains(..., '-test')` is case-insensitive, so this
+            # must be too: `v1.2.3-Test1` is a rehearsal, never a real release.
+            lower="$(printf '%s' "$REF_NAME" | tr '[:upper:]' '[:lower:]')"
+            case "$lower" in
+              *-test*) mode="test";;
+              *)       mode="real";;
+            esac
+          fi
+          echo "mode=$mode" >> "$GITHUB_OUTPUT"
+          echo "mode: $mode" >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Refuse a tag that names another version
+        if: github.event_name == 'push'
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          # `vX.Y.Z` and `vX.Y.Z-test<anything>` (in any case) both name version X.Y.Z.
+          named="${REF_NAME#v}"
+          named="${named%%-[Tt][Ee][Ss][Tt]*}"
+          declared="$(uv version --short)"
+          if [ "$named" != "$declared" ]; then
+            echo "::error::tag $REF_NAME names version $named but pyproject.toml declares $declared"
+            exit 1
+          fi
+      - name: Test before publishing
+        # The gate in front of the immutable upload. `--locked` fails when uv.lock does not
+        # match pyproject.toml.
+        run: uv sync --locked && uv run --locked pytest
+      - name: Rewrite the version to a unique dev release (rehearsal only)
+        if: steps.mode.outputs.mode != 'real'
+        # TestPyPI never replaces a file, so each rehearsal needs a version of its own. `--frozen`
+        # leaves uv.lock alone: the build does not read it.
+        run: uv version "$(uv version --short).dev$((GITHUB_RUN_NUMBER * 100 + GITHUB_RUN_ATTEMPT))" --frozen
+      - name: Build once
+        id: build
+        run: |
+          set -euo pipefail
+          uv build -o dist
+          test "$(find dist -name '*.whl' | wc -l)" -eq 1
+          test "$(find dist -name '*.tar.gz' | wc -l)" -eq 1
+          echo "version=$(uv version --short)" >> "$GITHUB_OUTPUT"
+          (cd dist && sha256sum -- *) >> "$GITHUB_STEP_SUMMARY"
+      - name: Refuse a wheel that lacks a module or a data file
+        run: uv run --no-project --python 3.12 scripts/check_wheel.py dist
+      - name: Install the wheel in clean environments and run the smoke test
+        run: |
+          set -euo pipefail
+          for py in 3.12 3.14; do
+            uv venv -q --python "$py" "$RUNNER_TEMP/venv-$py"
+            uv pip install -q --python "$RUNNER_TEMP/venv-$py/bin/python" dist/*.whl
+            (cd "$RUNNER_TEMP" && "$RUNNER_TEMP/venv-$py/bin/python" -I "$GITHUB_WORKSPACE/scripts/smoke_installed.py")
+          done
+      # Everything below, including the upload, uses THIS artifact: never rebuild.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+          overwrite: true
+
+  # ---- the irreversible step ------------------------------------------------
+
+  publish:
+    needs: prepare
+    runs-on: ubuntu-latest
+    # `dry-run` is an unprotected environment with no PyPI trust: a dry run
+    # still starts this job (so the graph is the same in every mode) but every
+    # upload step below is skipped.
+    environment: ${{ (needs.prepare.outputs.mode == 'real' && 'pypi') || (needs.prepare.outputs.mode == 'test' && 'testpypi') || 'dry-run' }}
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist
+      - name: Dry run, nothing is uploaded
+        if: needs.prepare.outputs.mode == 'dry'
+        run: |
+          echo "dry run: would upload $(find dist -type f | wc -l) files" >> "$GITHUB_STEP_SUMMARY"
+      # Rehearsal versions are unique per run, so there is nothing to skip: an
+      # existing file means something is wrong, and the upload must say so.
+      - name: Publish to TestPyPI
+        if: needs.prepare.outputs.mode == 'test'
+        # Every action in this job is pinned to a commit SHA. This job holds
+        # id-token: write for PyPI Trusted Publishing, so a compromised revision
+        # of a tag or of a moving branch such as release/v1 could mint a token
+        # and publish under this project's name.
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+          skip-existing: false
+      # There is one distribution, so a file already on the index means this
+      # version was published before: the upload must fail, not skip it.
+      # Skipping would report success for bytes this run never uploaded.
+      - name: Publish to PyPI
+        if: needs.prepare.outputs.mode == 'real'
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist
+
+  # ---- the published file, read back ----------------------------------------
+
+  verify-index:
+    needs: [prepare, publish]
+    if: needs.prepare.outputs.mode != 'dry'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.14"]
+    permissions:
+      contents: read
+    env:
+      VERSION: ${{ needs.prepare.outputs.version }}
+      INDEX: ${{ needs.prepare.outputs.mode == 'test' && 'https://test.pypi.org/simple/' || 'https://pypi.org/simple/' }}
+      PY_VERSION: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Install the published wheel and run the smoke test
+        run: |
+          set -euo pipefail
+          # The index can lag the upload, so ask every 20 s, up to 30 times. pip's own
+          # cache is off: it would keep serving the index page it read before the upload.
+          downloaded=false
+          for attempt in $(seq 1 30); do
+            if python3 -m pip download --no-cache-dir --no-deps --only-binary :all: \
+                --index-url "$INDEX" "continuo-contracts==$VERSION" -d "$RUNNER_TEMP/dl"; then
+              downloaded=true
+              break
+            fi
+            echo "attempt $attempt of 30: continuo-contracts==$VERSION is not served by $INDEX yet"
+            if [ "$attempt" -lt 30 ]; then
+              sleep 20
+            fi
+          done
+          if [ "$downloaded" != true ]; then
+            echo "::error::continuo-contracts==$VERSION was not served by $INDEX after 30 attempts"
+            exit 1
+          fi
+          fetched=("$RUNNER_TEMP"/dl/*.whl)
+          built=(dist/*.whl)
+          test "${#fetched[@]}" -eq 1
+          test "${#built[@]}" -eq 1
+          # The index must serve the very file this run built.
+          cmp "${fetched[0]}" "${built[0]}"
+          uv venv -q --python "$PY_VERSION" "$RUNNER_TEMP/venv"
+          # PyYAML comes from PyPI first: TestPyPI holds copies of real project names,
+          # so it must not supply a dependency.
+          uv pip install -q --python "$RUNNER_TEMP/venv/bin/python" "PyYAML>=6.0"
+          uv pip install -q --python "$RUNNER_TEMP/venv/bin/python" --no-deps "${fetched[0]}"
+          (cd "$RUNNER_TEMP" && "$RUNNER_TEMP/venv/bin/python" -I "$GITHUB_WORKSPACE/scripts/smoke_installed.py")