[v1.0] Pin and verify the release build toolchain

[codeforester]

Goal

Make release artifacts derive from a reviewed, reproducible build toolchain instead of mutable latest packages.

Background

The release workflow installs unversioned latest build and twine immediately before creating distributions:

base-cli/.github/workflows/package.yml

Lines 95 to 107 in 8a93d22

	- name: Prepare clean artifact destination
	run: |
	git clean -ffdx
	mkdir -p dist
	- name: Install build and validation tools
	run: python -m pip install --upgrade build twine
	- name: Build sdist and wheel
	run: python -m build --sdist --wheel --outdir dist
	- name: Validate artifact contents and metadata
	run: python scripts/validate_package_artifact.py dist

. PEP 517 then resolves the ranged setuptools>=68,<77 build requirement at run time:

base-cli/pyproject.toml

Lines 1 to 5 in 8a93d22

	[build-system]
	# Keep the generated core metadata at 2.3 until the pinned publisher action's
	# bundled twine/pkginfo stack accepts Metadata-Version 2.4.
	requires = ["setuptools>=68,<77"]
	build-backend = "setuptools.build_meta"

.

The GitHub Actions themselves are commit-pinned and the resulting artifacts are hashed/attested, but attestations only prove what this run produced. A mutable toolchain can change artifact bytes or expose the release path to a newly compromised dependency without a repository diff.

Scope

• Define a reviewed constraint/lock mechanism for release-only build and validation tools, including transitive dependencies where practical.
• Make the package job install that exact toolchain with integrity verification.
• Add an intentional update workflow and compatibility test for toolchain refreshes.
• Check build reproducibility or explain every accepted nondeterministic field.

Acceptance Criteria

• Release builds do not install unconstrained latest build, twine, setuptools, wheel, or their release-path dependencies.
• The resolved versions and integrity data are reviewable in the repository.
• Dependency updates arrive through a reviewed automated PR or documented maintenance command.
• Two clean builds of the same source revision and toolchain produce identical wheel/sdist digests, or CI reports a precise reviewed exception.
• SBOM/provenance metadata identifies the build toolchain as well as the source revision.
• TestPyPI, PyPI, smoke, attestation, and GitHub Release jobs consume the same reviewed artifacts.
• The change remains compatible with [v1.0] Add SBOM, provenance attestations, and reproducible release verification #195 and trusted publishing.

Validation

Build twice in isolated clean environments; compare artifacts and metadata; test a deliberate constraint drift and hash mismatch; run TestPyPI rehearsal.

Non-Goals

• Do not freeze consumer runtime dependency windows to one version.
• Do not replace PyPI trusted publishing or GitHub attestations.

Project Fields

• Status: Backlog
• Priority: P1
• Area: Packaging
• Initiative: v1.0 Readiness
• Size: M

Ownership

• Assignee: @codeforester