build: add clean-room package validation (#282)

* build: add clean-room package gate

* fix: complete package gate coverage

Author: lfnovo

.maintainer/README.md

@@ -19,10 +19,10 @@ Commands remain canonical in `AGENTS.md` and `Makefile`; contribution and
 architecture policy remain in `CONTRIBUTING.md` and `ARCHITECTURE.md`.
 Read the relevant module-level `AGENTS.md` when reviewing its implementation.
 
-Review, triage and Discussions are configured. The owner confirmed `make tag`
-as the release trigger. The package-install gate is deferred to
-[issue #279](https://github.com/lfnovo/esperanto/issues/279), so release configuration
-remains incomplete until that command exists.
+Review, triage, Discussions and release are configured. The owner confirmed
+`make tag` as the release trigger. `make package-check` is the canonical
+clean-room package gate implemented by
+[issue #279](https://github.com/lfnovo/esperanto/issues/279).
 A valid profile is not evidence that release checks have passed.
 Discussions is enabled, with its live category IDs in `profile.toml`.
 The application smoke skill does not apply to this library. Real-provider

.maintainer/decisions.md

@@ -18,3 +18,14 @@ been made by this profile bootstrap.
   .github/workflows/publish.yml; verified GitHub settings, categories and labels;
   https://github.com/lfnovo/esperanto/issues/279.
 - This authorizes profile adoption and repository setup, not a release publication.
+
+## 2026-09-05 — Implement the package gate for 2.27.0
+
+- Decision: implement issue #279 now and make `make package-check` the mandatory
+  clean-room artifact gate for the 2.27.0 release.
+- Decision: the gate verifies fresh wheel and sdist builds, isolated bare
+  installs, a wheel rebuilt from the sdist, every declared optional extra and
+  SHA-256 artifact identities.
+- Evidence: explicit maintainer approval during the 2.27.0 release session and
+  local execution of `make package-check` on Python 3.13.11.
+- This decision configures the gate; it does not authorize merging or publishing.

.maintainer/profile.toml

@@ -57,7 +57,7 @@ merge_own_prs = "ask-once-per-session"
 
 [artifacts.pypi]
 package = "esperanto"
-gate = "TODO implement canonical package-check gate in issue #279; see .maintainer/release/runbook.md"
+gate = "make package-check"
 surfaces = ["library"]
 extras = ["transformers", "validation"]
 identity = "sha256"

.maintainer/release/runbook.md

@@ -16,20 +16,19 @@ use the narrower validator documented in AGENTS.md.
 Record the candidate SHA, interpreter, command, exit status and evidence. CI's
 extra mxbai-rerank install and its Python matrix are documented in test.yml.
 
-## Package gate — missing canonical command
+## Package gate
 
-TODO: define and validate a canonical build-and-clean-room-install command in
-AGENTS.md or Makefile, then replace artifacts.pypi.gate with its reference.
-The owner deferred implementation to [issue #279](https://github.com/lfnovo/esperanto/issues/279).
-The existing uv build step in publish.yml is build-only; it cannot satisfy this gate.
+Run `make package-check`. The command builds fresh wheel and sdist artifacts in
+a temporary directory, checks their metadata and packaged runtime files, and
+records SHA-256 identities. It installs the wheel outside the checkout with
+isolated Python, verifies a bare import and credential-free factory discovery,
+then builds a second wheel from the sdist and repeats the clean-room smoke. It
+also resolves the `transformers` and `validation` extras independently. The
+existing uv build step in publish.yml is build-only and cannot satisfy this gate.
 
-The gate must build wheel and sdist into a clean output location, check metadata
-against the candidate version, inspect packaged assets, install the wheel outside
-the checkout with isolated Python imports, import Esperanto and exercise a
-credential-free public API call. Confirm optional dependencies stay optional and
-that both transformers and validation extras resolve. Verify the sdist can build
-an installable wheel. Record SHA-256 identities and actual module origins.
-No package-gate pass or release GO is possible until this evidence exists.
+Capture the command output as release evidence. It includes the interpreter,
+artifact identities and actual module origins. A package-gate pass applies only
+to those exact locally built artifacts and candidate revision.
 
 ## Bucket C — maintainer-run integrations
 
@@ -68,8 +67,19 @@ Publish rebuilds the artifacts: distinguish tested local builds from index build
 If creating GitHub release notes, attach approved notes to the existing tag and
 verify the release page; publish.yml does not create a GitHub Release itself.
 
-TODO: document canonical index-install verification commands alongside the package
-gate. This verification completes publication; it cannot run before publication.
+Install the exact published version outside the checkout with:
+
+```bash
+check_dir="$(mktemp -d)"
+cd "$check_dir"
+uv run --isolated --no-project --with "esperanto==<version>" \
+  python -I -c 'import esperanto; print(esperanto.__file__)'
+```
+
+Repeat with `esperanto[transformers]==<version>` and
+`esperanto[validation]==<version>`, download the wheel and sdist from PyPI, and
+record their SHA-256 identities. This verification completes publication; it
+cannot run before publication.
 
 ## Cleanup
 

.maintainer/release/test-matrix.md

@@ -10,7 +10,7 @@ Record passed, failed, not-run and not-applicable checks with revision and evide
 | Default mocked suite | commands.validator -> make test | pytest excludes release marker |
 | Lint | commands.ruff -> AGENTS.md | Same check as lint.yml |
 | Types | commands.mypy -> AGENTS.md | src/esperanto, as in lint.yml |
-| Packaging | artifacts.pypi.gate | Missing canonical clean-room gate; blocks release |
+| Packaging | artifacts.pypi.gate -> make package-check | Fresh wheel/sdist, metadata, packaged runtime files, clean-room imports, extras and SHA-256 identities |
 
 The setup target installs all extras. CI additionally installs mxbai-rerank.
 CI tests 3.10/3.11/3.12; package metadata also supports 3.13. Track actual coverage.
@@ -24,8 +24,6 @@ Do not claim a provider was exercised merely because a shared base test passed.
 
 ## Bucket B — investment candidates
 
-- Implement the package gate described in runbook.md, including wheel/sdist and extras
-  ([issue #279](https://github.com/lfnovo/esperanto/issues/279), deferred by the owner).
 - Add Python 3.13 CI coverage if the maintainer elects to cover the full declared range.
 - Reconcile the CI-specific mxbai-rerank setup with local validation documentation.
 

AGENTS.md

@@ -242,6 +242,7 @@ All providers use utility mixins:
 - **Run all tests**: `uv run pytest -v`
 - **Run specific test**: `uv run pytest tests/providers/llm/test_openai.py -v`
 - **Run integration tests**: `uv run pytest tests/integration/ -v`
+- **Validate package artifacts**: `make package-check`
 - **Check types**: `uv run mypy src/esperanto`
 - **Fix lint issues**: `uv run ruff check . --fix`
 

CONTRIBUTING.md

@@ -248,10 +248,13 @@ Run the release suite **before tagging a release** — it's the last gate that c
 3. Run `uv run pytest` (default, mocked) — must be green.
 4. Run `uv run ruff check .` and `uv run mypy src/esperanto` — must be green.
 5. **Run `uv run pytest -m release`** — must be green or have only known-tracked xfails.
-6. Bump version, commit, tag, push tag.
-7. Build + publish.
+6. Bump the version, regenerate `uv.lock`, and run `make package-check` against
+   the exact candidate — its clean-room wheel/sdist checks must be green.
+7. Commit the release cut, then repeat any gate invalidated by that commit.
+8. After the explicit release GO, run `make tag`; its tag push triggers the
+   publish workflow.
 
-If step 5 surfaces a real regression, the release waits.
+If a gate surfaces a real regression, the release waits.
 
 **6. Audio fixture**
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup ruff lint test
+.PHONY: setup ruff lint test package-check
 
 setup:
 	uv venv
@@ -13,6 +13,9 @@ ruff:
 test:
 	uv run pytest -v
 
+package-check:
+	uv run python scripts/package_check.py
+
 
 build-docs:
 	repomix . --include "**/*.py" --compress --style xml -o ai_docs/all_docs.txt
@@ -23,4 +26,3 @@ tag:
 	echo "Creating tag v$$version"; \
 	git tag "v$$version"; \
 	git push origin "v$$version"
-