ci: split build from publish, gate OIDC with environment

[gavinsharp]

Summary

Implements step 2 of the publish-hardening plan (Python SDK). Splits the credential-bearing job from the build toolchain so no dependency installer ever runs in the same job as the PyPI OIDC token.

New topology:

compile -> test -> tag -> build-artifact -> publish

• build-artifact (new, no secrets): poetry build, then upload dist/ via actions/upload-artifact.
• publish (rewritten): no checkout, no setup-python, no Poetry. Downloads the artifact, then runs pypa/gh-action-pypi-publish (upload-only). actions/download-artifact@v8 verifies the downloaded bundle against GitHub's recorded digest by default (digest-mismatch: error).
• Workflow-root permissions: {} with per-job grants. publish gets id-token: write + contents: read and nothing else.
• environment: pypi-production on publish — so the PyPI Trusted Publisher binding and the environment's deployment rules can pin OIDC minting to refs/heads/main.
• concurrency group keyed on the ref; cancels superseded runs on PR branches but never on main (a mid-flight cancel would orphan the tag from the publish).
• Shared PYTHON_VERSION / POETRY_VERSION env vars replace the version strings previously duplicated across jobs (and compile now pins Python like the others).
• All new uses: are SHA-pinned with trailing version comments (actions/upload-artifact@v7.0.1, actions/download-artifact@v8.0.1).
• .github/workflows/ci.yml is in .fernignore, so Fern regen will not clobber this.

A bespoke SHA256SUMS build/verify step between the jobs was considered and dropped: it only defends against a GitHub-side artifact-store compromise, which is out of scope, and download-artifact@v8's built-in digest check already covers the realistic threat (transit corruption / tampering).

Required follow-up (outside this PR)

These are GitHub/PyPI configuration changes that must land for the new bindings to be enforced:

• Create the pypi-production GitHub Environment in repo settings, with a deployment-branch rule restricting it to refs/heads/main.
• Update the PyPI Trusted Publisher binding for this repo to require environment name pypi-production.
• Confirm branch protection is enabled on main (the refs/heads/main restriction is only as strong as who can push to main).

Until the environment is created, GitHub will auto-create it with no protection rules, so this PR is safe to merge before the manual steps land — the security improvements just don't fully take effect until then.

Test plan

• Merge to main with no version bump: tag job sets should_publish=false, build-artifact and publish are skipped.
• Bump version in pyproject.toml, merge to main: tag creates the release, build-artifact produces and uploads python-dist, publish downloads it and publishes to PyPI.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the release/publish pipeline and PyPI OIDC wiring; misconfiguration or a failed artifact handoff could block or break publishes until GitHub environment and PyPI Trusted Publisher settings are aligned.

Overview
Hardens the main-branch PyPI release path by splitting what used to be a single publish job into build-artifact → publish: Poetry builds and uploads dist/ as a short-lived artifact; publish only downloads that artifact (with digest verification) and runs gh-action-pypi-publish, with no checkout, Poetry, or dependency install in the OIDC-bearing job.

Adds workflow-root permissions: {} with per-job grants, environment: pypi-production on publish for Trusted Publisher / branch rules, and concurrency that cancels in-progress runs on non-main refs but not on main (to avoid orphaning a tag from a half-finished upload). Centralizes PYTHON_VERSION / POETRY_VERSION across jobs and bumps verify-openapi-spec / sync-fern-artifacts reusable workflows to 1.0.3.

^{Reviewed by Cursor Bugbot for commit 5a2edb3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5a2edb3. Configure here.}