From 744414b66ae151135214da58174e1f24b11027e7 Mon Sep 17 00:00:00 2001 From: luisleo526 <20812494+luisleo526@users.noreply.github.com> Date: Sun, 15 Nov 2026 03:26:28 +0800 Subject: [PATCH 1/2] Require exact-commit hub CI and facts proof before publication Guard tag creation, image readiness, finalization and fanout with complete main-push CI and facts validation bound to the exact release/facts commits. Keep the existing release identity and authorization checks, and exercise missing, incomplete, stale and mismatched proof through the real reader. --- .github/workflows/facts-fanout.yml | 19 +- .github/workflows/handle-upstream.yml | 9 +- .github/workflows/publish.yml | 16 + .github/workflows/release-finalize.yml | 11 +- .github/workflows/release-reconcile.yml | 7 + .github/workflows/release-redeliver.yml | 7 + docs/release-main-proof.md | 91 +++++ scripts/release_main_proof.py | 326 ++++++++++++++++ tests/test_release_binding_workflows.py | 227 ++++++++++- tests/test_release_main_proof.py | 488 ++++++++++++++++++++++++ tests/test_release_workflows.py | 130 ++++++- 11 files changed, 1296 insertions(+), 35 deletions(-) create mode 100644 docs/release-main-proof.md create mode 100644 scripts/release_main_proof.py create mode 100644 tests/test_release_main_proof.py diff --git a/.github/workflows/facts-fanout.yml b/.github/workflows/facts-fanout.yml index 17c13eb..1e005c4 100644 --- a/.github/workflows/facts-fanout.yml +++ b/.github/workflows/facts-fanout.yml @@ -17,6 +17,7 @@ on: permissions: contents: read + actions: read # This signal serializes independently of descriptions and release automation. concurrency: @@ -53,10 +54,15 @@ jobs: python3 scripts/facts_fanout.py prepare --facts facts/facts.json --dry-run "$DRY_RUN" \ --output-dir "$RUNNER_TEMP/fanout-source" --github-output "$GITHUB_OUTPUT" \ --receipt "$RUNNER_TEMP/fanout-audit/prepare.json" + - name: Require full main proof for the facts snapshot + id: main-proof + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" - name: Mint consumer token id: app if: >- - steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && + steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && steps.main-proof.outcome == 'success' && github.ref == 'refs/heads/main' && github.ref_protected && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && vars.FACTS_WEB_DISPATCH_ENABLED == 'true' @@ -72,7 +78,7 @@ jobs: permission-contents: write github-api-url: https://api.github.com - name: Send the validated signal and record its status - if: ${{ !cancelled() && steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' }} + if: ${{ !cancelled() && steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && steps.main-proof.outcome == 'success' }} env: FACTS_READ_TOKEN: ${{ github.token }} FACTS_WEB_REPOSITORY: ${{ secrets.FACTS_WEB_REPOSITORY }} @@ -122,10 +128,15 @@ jobs: python3 scripts/facts_fanout.py prepare --facts facts/facts.json --dry-run "$DRY_RUN" \ --output-dir "$RUNNER_TEMP/fanout-source" --github-output "$GITHUB_OUTPUT" \ --receipt "$RUNNER_TEMP/fanout-audit/prepare.json" + - name: Require full main proof for the facts snapshot + id: main-proof + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" - name: Mint consumer token id: app if: >- - steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && + steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && steps.main-proof.outcome == 'success' && github.ref == 'refs/heads/main' && github.ref_protected && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && vars.FACTS_LICENSE_DISPATCH_ENABLED == 'true' @@ -141,7 +152,7 @@ jobs: permission-contents: write github-api-url: https://api.github.com - name: Send the validated signal and record its status - if: ${{ !cancelled() && steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' }} + if: ${{ !cancelled() && steps.source.outcome == 'success' && steps.source.outputs.mint_allowed == 'true' && steps.main-proof.outcome == 'success' }} env: FACTS_READ_TOKEN: ${{ github.token }} FACTS_WEB_REPOSITORY: pineforge-license diff --git a/.github/workflows/handle-upstream.yml b/.github/workflows/handle-upstream.yml index 94a4ed9..e499c48 100644 --- a/.github/workflows/handle-upstream.yml +++ b/.github/workflows/handle-upstream.yml @@ -29,6 +29,7 @@ concurrency: permissions: contents: read # the App token does the push + actions: read # exact release-commit main-push proof issues: write # neutral failure incidents only jobs: @@ -337,6 +338,7 @@ jobs: - name: Bump VERSION, commit, tag if: steps.decide.outputs.mode == 'bump' env: + MAIN_PROOF_TOKEN: ${{ github.token }} E: ${{ steps.decide.outputs.engine }} C: ${{ steps.decide.outputs.codegen }} H: ${{ steps.decide.outputs.hpo }} @@ -356,6 +358,7 @@ jobs: # release commit (VERSION = the pair version). Tag that commit. commit="$(git log HEAD --format=%H -n 1 --fixed-strings --grep="chore(release): v${RELEASE} — ${components}")" [ -n "$commit" ] || { echo "::error::VERSION is ${RELEASE} but main has no release commit for it; refusing to tag"; exit 1; } + python3 scripts/release_main_proof.py commit --sha "$commit" --wait-seconds 1800 git tag -a "v${RELEASE}" "$commit" -m "$(tag_message "$RELEASE")" git push origin "v${RELEASE}" line="pushed v${RELEASE} at ${commit} (${components}); after the tag exists on main and handle-upstream is green, a user with write access must run: gh workflow run publish.yml --repo pineforge-4pass/pineforge-release --ref main -f tag=v${RELEASE}" @@ -394,8 +397,12 @@ jobs: git add VERSION ${harness} git diff --cached --quiet && { echo "::error::nothing staged — refusing empty release"; exit 1; } git commit -m "chore(release): v${next} — ${components}" - git tag -a "v${next}" -m "$(tag_message "$next")" + commit="$(git rev-parse HEAD)" + # Push the FINAL release commit first so its own full main-push CI + # and facts run can execute. Base/PR proof cannot authorize its tag. git push origin HEAD:main + python3 scripts/release_main_proof.py commit --sha "$commit" --wait-seconds 1800 + git tag -a "v${next}" "$commit" -m "$(tag_message "$next")" git push origin "v${next}" line="pushed v${next} (${components}); after the tag exists on main and handle-upstream is green, a user with write access must run: gh workflow run publish.yml --repo pineforge-4pass/pineforge-release --ref main -f tag=v${next}" echo "::notice title=pineforge publish needed::${line}" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 9ba40ba..36168bc 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -90,6 +90,7 @@ jobs: PF_CI_LABELS: '["self-hosted","pf-ci","pf-ci-x64"]' permissions: contents: write # GitHub lists draft candidates only with push access + actions: read outputs: exists: ${{ steps.candidate.outputs.exists }} tag: ${{ needs.tag-guard.outputs.tag }} @@ -104,6 +105,12 @@ jobs: with: ref: ${{ needs.tag-guard.outputs.sha }} persist-credentials: false + - name: Require full main proof before candidate reuse + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ needs.tag-guard.outputs.tag }} + RELEASE_SHA: ${{ needs.tag-guard.outputs.sha }} + run: python3 scripts/release_main_proof.py tag --tag "$TAG" --sha "$RELEASE_SHA" - name: Reuse an already verified candidate id: candidate env: @@ -122,6 +129,7 @@ jobs: permissions: contents: write # append verified candidate to its draft release packages: write # push to GHCR + actions: read outputs: prerelease: ${{ steps.pair.outputs.prerelease }} steps: @@ -142,6 +150,13 @@ jobs: python-version: '3.12' - run: python3 -m pip install -r facts/requirements-validation.txt + - name: Require full main proof before image publication + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ env.RELEASE_TAG }} + RELEASE_SHA: ${{ needs.tag-guard.outputs.sha }} + run: python3 scripts/release_main_proof.py tag --tag "$TAG" --sha "$RELEASE_SHA" + - name: Assert tag matches VERSION env: TAG: ${{ env.RELEASE_TAG }} @@ -690,6 +705,7 @@ jobs: contents: write packages: write issues: write + actions: read failure-report: needs: [tag-guard, prepare, publish, notify-consumers] diff --git a/.github/workflows/release-finalize.yml b/.github/workflows/release-finalize.yml index 77b0395..429581f 100644 --- a/.github/workflows/release-finalize.yml +++ b/.github/workflows/release-finalize.yml @@ -23,6 +23,7 @@ permissions: jobs: finalize: + if: github.ref == 'refs/heads/main' # Job-level concurrency also applies when invoked through workflow_call. # Serialize alias decisions and persistent delivery reservations together. concurrency: @@ -35,6 +36,7 @@ jobs: contents: write packages: write issues: write + actions: read outputs: deliveries: ${{ steps.delivery-output.outputs.deliveries }} compute_configuration_error: ${{ steps.ready.outputs.compute_configuration_error }} @@ -75,7 +77,7 @@ jobs: RELEASE_APPLICATION_MAX_AGE_MINUTES: ${{ vars.RELEASE_APPLICATION_MAX_AGE_MINUTES || '1440' }} run: | set -euo pipefail - python3 scripts/release_pipeline.py finalize --tag "$TAG" --output "$RUNNER_TEMP/deliveries.json" + python3 scripts/release_main_proof.py finalize --tag "$TAG" --output "$RUNNER_TEMP/deliveries.json" - name: Publish delivery matrix id: delivery-output if: ${{ always() }} @@ -127,6 +129,7 @@ jobs: permissions: contents: write # append neutral delivery audit assets in this hub only issues: write + actions: read strategy: fail-fast: false matrix: @@ -145,6 +148,12 @@ jobs: with: ref: main persist-credentials: false + - name: Require full main proof before release delivery + id: main-proof + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ matrix.tag }} + run: python3 scripts/release_main_proof.py delivery --tag "$TAG" - name: Require one configured consumer repository shell: bash env: diff --git a/.github/workflows/release-reconcile.yml b/.github/workflows/release-reconcile.yml index e015dcc..da9749f 100644 --- a/.github/workflows/release-reconcile.yml +++ b/.github/workflows/release-reconcile.yml @@ -7,6 +7,7 @@ on: permissions: contents: read + actions: read issues: write concurrency: @@ -15,6 +16,7 @@ concurrency: jobs: producers: + if: github.ref == 'refs/heads/main' # pineforge-release runs on GitHub-hosted runners; standing exception for this repository runs-on: ubuntu-latest environment: release-automation @@ -23,6 +25,11 @@ jobs: with: ref: main persist-credentials: false + - name: Require full main proof before producer reconciliation + id: main-proof + env: + GH_TOKEN: ${{ github.token }} + run: python3 scripts/release_main_proof.py commit --sha "$(git rev-parse HEAD)" - name: Mint hub-only dispatch token id: app uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 diff --git a/.github/workflows/release-redeliver.yml b/.github/workflows/release-redeliver.yml index 1c2ac1e..5e8ec00 100644 --- a/.github/workflows/release-redeliver.yml +++ b/.github/workflows/release-redeliver.yml @@ -36,6 +36,7 @@ jobs: permissions: contents: write # append one neutral redelivery audit asset in this hub issues: write + actions: read steps: - name: Stop automatic apt upgrades (until the release image is rebaked) shell: bash @@ -86,6 +87,12 @@ jobs: RELEASE_COMPUTE_FIRST_PAIR: ${{ vars.RELEASE_COMPUTE_FIRST_PAIR }} run: | python3 scripts/release_pipeline.py redeliver-check --tag "$TAG" --consumer "$CONSUMER" + - name: Require full main proof before release redelivery + id: main-proof + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ inputs.tag }} + run: python3 scripts/release_main_proof.py delivery --tag "$TAG" - name: Require one configured consumer repository id: target shell: bash diff --git a/docs/release-main-proof.md b/docs/release-main-proof.md new file mode 100644 index 0000000..39cd244 --- /dev/null +++ b/docs/release-main-proof.md @@ -0,0 +1,91 @@ +# Main-commit proof before publication + +Release publication requires the hub's own complete CI and facts validation +for the exact release commit on `main`. A green pull request, merge queue, +producer workflow, other commit, or similarly named check cannot authorize it. +The existing tag ancestry, producer artifacts, runtime smoke, measured facts, +immutable manifest, and consumer policies continue to apply. + +`scripts/release_main_proof.py` reads GitHub's public hub repository, workflow, +run, and job identities. It resolves each workflow by its file path and numeric +ID, selects its newest `push` run for `main` at the requested 40-character SHA, +and reads that run's current attempt. Both workflows and every job below must +be `completed` with conclusion `success`: + +| Workflow | Complete expected job inventory | +| --- | --- | +| `python-test.yml` | `authz`, `changes`, `fingerprint-canonical`, `release-rules`, `description-renderer`, `release-ready-replay`, `release/ready` | +| `facts-validate.yml` | `authz`, `validate` | + +The reader checks the repository and head repository identities, workflow +path, event, branch, SHA, main ancestry, run ID, attempt, and each job's source +identity. It reads paginated results and refuses incomplete or ambiguous +inventories. Missing, red, running, cancelled, skipped, neutral, or malformed +proof refuses publication. An older successful run cannot hide a newer failed +or unfinished run. There is no success override or supplied proof-file input. +The unit fixtures model endpoint responses; production always reads GitHub. +Jobs are fetched through the selected attempt's endpoint; when GitHub includes +the optional per-job attempt field, it must match that endpoint's attempt. + +## Publication boundaries + +| Route | Required proof | +| --- | --- | +| Fresh upstream release | Push the final VERSION and harness commit to `main`, prove that exact SHA, then create and push its annotated tag. | +| Retag recovery | Prove the existing final release commit before creating its missing tag. | +| Candidate reuse and image build | Re-resolve the existing tag, compare it with the SHA admitted by `tag-guard`, and prove that SHA before reuse or image publication. | +| Every finalizer trigger | Guard each selected candidate's tag and `hub_commit`; prove the facts commit actually read before writing its manifest or publishing aliases and readiness. | +| Replaying an existing manifest | Prove its release commit and its immutable bound facts commit before replaying publication. | +| Normal consumer delivery and redelivery | Prove the published manifest's release and facts commits before minting a consumer token. | +| Facts web and license signals | Prove the commit in the prepared facts payload, with its facts digest bound to that snapshot, before minting or sending. | +| Producer reconciliation | Prove the checked-out main SHA before replaying producer events; the handler separately proves the release commit it creates. | + +`finalize` in the new helper calls the existing `release_pipeline.finalize_all` +with guarded storage and source reads. This covers reusable, manual, scheduled, +and facts-push finalization, including an empty-tag candidate sweep. It avoids a +preflight over one candidate list followed by publication from a newly selected +list. Facts may arrive in a later main commit than the release commit, so each +of those exact SHAs requires its own full CI and facts proof. Historical rows +read only to compare versions do not acquire publication authority. + +The handler waits up to 1,800 seconds for missing or unfinished runs, without +dispatching or rerunning CI. Failed proof stops immediately. If proof never +becomes complete, the main commit remains available and no release tag is +created. Other routes refuse unavailable proof at their normal wake-up; their +existing recovery triggers remain responsible for subsequent attempts. Old +releases without the required proof receive no exemption. + +The workflows grant their hub token `actions: read` for proof reads; consumer +tokens retain their existing scopes. Proof snapshots are cached only within +one operation, never persisted as a reusable authorization. GitHub reads and +publication are separate API operations; existing immutable tags and assets +remain part of the release contract. + +## Focused controls + +Run these in an authorized test environment, one module at a time: + +```sh +python3 -m py_compile scripts/release_main_proof.py tests/test_release_main_proof.py tests/test_release_workflows.py tests/test_release_binding_workflows.py +python3 -m unittest discover -s tests -p 'test_release_main_proof.py' -v +python3 -m unittest discover -s tests -p 'test_release_workflows.py' -v +python3 -m unittest discover -s tests -p 'test_release_binding_workflows.py' -v +python3 -m unittest discover -s tests -p 'test_facts_fanout.py' -v +python3 -m unittest discover -s tests -p 'test_release_redeliver.py' -v +python3 tools/release-dry-run/dry_run.py --ready +``` + +The new controls cover valid identities and full-green acceptance, each absent +workflow and job, failed or unfinished proof, incorrect SHA/event/repository, +skipped proof, stale attempts, pagination, finalizer publication refusal, and +the owned workflow boundaries. Existing workflow text pins and shell replay +bridges pin the guarded finalizer entrypoint and proof-reader calls. The shell +replays serialize GitHub responses and execute the real reader for tag, +candidate, image, and redelivery boundaries. Their fixture clock expires an +unfinished handler wait without replacing its decision. Removed, softened, +or late guards have negative controls alongside the full-green controls. + +Source changes and offline controls do not establish live release readiness. +The normal pull-request CI, review and merge route still applies, followed by +the required CI on the final main release commit and the normal publication +and consumer checks. diff --git a/scripts/release_main_proof.py b/scripts/release_main_proof.py new file mode 100644 index 0000000..6603c20 --- /dev/null +++ b/scripts/release_main_proof.py @@ -0,0 +1,326 @@ +#!/usr/bin/env python3 +"""Require this hub's complete successful main-push CI on an exact commit. + +The proof reader only GETs public hub identities. Publication still uses the +existing release pipeline; its candidate and facts reads are guarded here so +scheduled reconciliation cannot select an unproved commit after a preflight. +""" +from __future__ import annotations + +import argparse +import os +from pathlib import Path +import sys +import time + +from release_artifacts import Client +from release_contract import (ASSET, CANDIDATE, COMMIT, HUB, Invalid, Pending, + decode, keys, match, payload, sha256, validate_candidate) + + +# These are the existing jobs, not new checks or caller-provided success flags. +# The inventory test compares them with the actual main-push workflows. +WORKFLOWS = { + "python-test.yml": frozenset({ + "authz", "changes", "fingerprint-canonical", "release-rules", + "description-renderer", "release-ready-replay", "release/ready", + }), + "facts-validate.yml": frozenset({"authz", "validate"}), +} +PREFIX = f"repos/{HUB}" + + +class ProofError(Invalid): + """No publication is authorized by this proof.""" + + +class ProofPending(ProofError): + """The handler may wait for a missing or unfinished main-push run.""" + + +def insist(condition, message): + if not condition: + raise ProofError(message) + + +def commit_sha(value): + try: + return match(COMMIT, value) + except Invalid: + raise ProofError("main proof requires an exact commit SHA") from None + + +def identifier(value): + insist(type(value) is int and 0 < value <= 2**53 - 1, "main proof has an invalid numeric identity") + return value + + +class MainProof: + def __init__(self, client): + self.client = client + # Successful snapshots live only for this operation, never on disk or + # in a workflow input. Failed and pending results are never cached. + self._proven = {} + self._repository = None + + def read(self, route): + insist(route == PREFIX or route.startswith(PREFIX + "/"), "main proof origin differs") + try: + return self.client.api(route) + except (Pending, Invalid, ValueError, OSError, KeyError, TypeError): + raise ProofError("main proof API unavailable or invalid") from None + + def pages(self, route, field): + result, total = [], None + for page in range(1, 11): + obj = self.read(route + ("&" if "?" in route else "?") + f"per_page=100&page={page}") + insist(type(obj) is dict and type(obj.get(field)) is list + and type(obj.get("total_count")) is int + and 0 <= obj["total_count"] <= 1000, "main proof pagination is incomplete") + if total is None: + total = obj["total_count"] + insist(total == obj["total_count"] and len(obj[field]) <= 100, + "main proof pagination changed") + result.extend(obj[field]) + insist(len(result) <= total, "main proof pagination count differs") + if len(result) == total: + return result + insist(len(obj[field]) == 100, "main proof pagination is truncated") + raise ProofError("main proof pagination limit exceeded") + + def repository(self): + if self._repository is None: + obj = self.read(PREFIX) + insist(type(obj) is dict and obj.get("full_name") == HUB + and obj.get("private") is False and obj.get("default_branch") == "main", + "main proof hub identity differs") + identifier(obj.get("id")) + self._repository = obj + return self._repository + + def run_identity(self, row, workflow, commit): + insist(type(row) is dict, "main proof run is malformed") + for name in ("id", "run_attempt", "run_number"): + identifier(row.get(name)) + insist(row.get("workflow_id") == workflow["id"] and type(row.get("workflow_id")) is int + and row.get("path") == workflow["path"], "main proof workflow identity differs") + insist(row.get("event") == "push" and row.get("head_branch") == "main" + and row.get("head_sha") == commit and row.get("pull_requests") == [], + "main proof is not this exact main-push commit") + for field in ("repository", "head_repository"): + repo = row.get(field) + insist(type(repo) is dict and repo.get("full_name") == HUB + and type(repo.get("id")) is int and repo["id"] == self.repository()["id"] + and repo.get("private") is False, "main proof run repository differs") + + @staticmethod + def completed(row): + if row.get("status") in {"queued", "in_progress", "waiting", "pending", "requested"}: + raise ProofPending("main proof is still running") + insist(row.get("status") == "completed" and row.get("conclusion") == "success", + "main proof did not complete successfully") + + def workflow_run(self, filename, expected_jobs, commit): + workflow = self.read(f"{PREFIX}/actions/workflows/{filename}") + insist(type(workflow) is dict, "main proof workflow is malformed") + wid = identifier(workflow.get("id")) + insist(workflow.get("path") == ".github/workflows/" + filename + and workflow.get("name") == filename.removesuffix(".yml") + and workflow.get("state") == "active", "main proof workflow definition differs") + runs = self.pages(f"{PREFIX}/actions/workflows/{wid}/runs" + f"?branch=main&event=push&head_sha={commit}&exclude_pull_requests=true", "workflow_runs") + if not runs: + raise ProofPending("main proof main-push run is missing") + for row in runs: + self.run_identity(row, workflow, commit) + insist(len({row["id"] for row in runs}) == len(runs), "main proof has duplicate runs") + # Never fall back to an earlier green run when the newest one is red + # or queued. A re-run's current attempt is read from the run endpoint. + selected = max(runs, key=lambda row: (row["run_number"], row["id"])) + self.completed(selected) + run = self.read(f"{PREFIX}/actions/runs/{selected['id']}") + self.run_identity(run, workflow, commit) + insist(all(run[field] == selected[field] for field in ("id", "run_number", "run_attempt")), + "main proof run attempt changed") + self.completed(run) + jobs = self.pages(f"{PREFIX}/actions/runs/{run['id']}/attempts/{run['run_attempt']}/jobs", "jobs") + names, ids = set(), set() + for job in jobs: + insist(type(job) is dict, "main proof job is malformed") + jid = identifier(job.get("id")) + name = job.get("name") + insist(type(name) is str and name not in names and jid not in ids, + "main proof job identity is ambiguous") + insist(type(job.get("run_id")) is int and job["run_id"] == run["id"] + and job.get("head_sha") == commit, "main proof job belongs to another commit or attempt") + # The attempt-specific endpoint is the authoritative binding. + # GitHub's optional per-job attempt field must agree if supplied. + if "run_attempt" in job: + insist(type(job["run_attempt"]) is int and job["run_attempt"] == run["run_attempt"], + "main proof job attempt differs") + self.completed(job) + names.add(name) + ids.add(jid) + insist(names == expected_jobs, "main proof full job inventory differs") + return {"run_id": run["id"], "run_attempt": run["run_attempt"]} + + def require_commit(self, commit): + commit_sha(commit) + if commit in self._proven: + return self._proven[commit] + self.repository() + comparison = self.read(f"{PREFIX}/compare/{commit}...main") + insist(type(comparison) is dict and comparison.get("status") in {"ahead", "identical"} + and type(comparison.get("base_commit")) is dict + and comparison["base_commit"].get("sha") == commit + and type(comparison.get("merge_base_commit")) is dict + and comparison["merge_base_commit"].get("sha") == commit, + "main proof commit is not reachable from main") + runs = {filename: self.workflow_run(filename, names, commit) for filename, names in WORKFLOWS.items()} + result = {"commit": commit, "runs": runs} + self._proven[commit] = result + return result + + def require_tag(self, tag, expected_sha=None): + try: + commit = self.client.tag_commit(HUB, tag) + except (Pending, Invalid, ValueError, OSError, KeyError, TypeError): + raise ProofError("main proof release tag is unavailable or invalid") from None + commit_sha(commit) + if expected_sha is not None: + insist(commit == commit_sha(expected_sha), "main proof tag and release commit differ") + return self.require_commit(commit) + + +class GuardedClient: + """Prove the facts commit actually selected by the existing finalizer.""" + + def __init__(self, client, checker): + self.client, self.checker = client, checker + + def __getattr__(self, name): + return getattr(self.client, name) + + def file(self, repo, commit, path): + if repo == HUB and path == "facts/facts.json": + self.checker.require_commit(commit) + return self.client.file(repo, commit, path) + + +class GuardedStore: + """Check each candidate before the real pipeline can publish its manifest.""" + + def __init__(self, store, checker): + self.store, self.checker = store, checker + self.candidates = set() + + def __getattr__(self, name): + return getattr(self.store, name) + + def manifest(self, row, raw): + event = payload(raw) + insist(row["tag_name"] == "v" + event["release_version"], "main proof manifest tag differs") + self.checker.require_tag(row["tag_name"], event["hub_commit"]) + self.checker.require_commit(event["facts"]["commit"]) + + def read(self, row, name): + raw = self.store.read(row, name) + if raw is not None and name == CANDIDATE: + candidate = validate_candidate(decode(raw)) + insist(row["tag_name"] == "v" + candidate["release_version"], "main proof candidate tag differs") + self.checker.require_tag(row["tag_name"], candidate["hub_commit"]) + self.candidates.add(row["tag_name"]) + elif raw is not None and name == ASSET and row["tag_name"] in self.candidates: + # Existing manifests can replay aliases too; they need proof for + # their bound facts commit, rather than whatever main is now. + self.manifest(row, raw) + return raw + + def put(self, row, name, raw): + if name == ASSET: + self.manifest(row, raw) + return self.store.put(row, name, raw) + + +def require_delivery(checker, tag): + import release_pipeline as pipeline + + store = pipeline.Store(checker.client) + row = store.get(tag) + insist(not row["draft"] and not any(asset["name"] == "release-rejected.json" for asset in row["assets"]), + "main proof delivery source is not published") + raw = store.read(row, ASSET) + insist(raw is not None, "main proof delivery manifest is missing") + guarded = GuardedStore(store, checker) + guarded.manifest(row, raw) + + +def require_facts_source(checker, directory): + obj = decode((directory / "payload.json").read_bytes()) + keys(obj, ("commit", "sha256", "dry_run")) + insist(type(obj["dry_run"]) is bool and obj["sha256"] == sha256((directory / "facts.json").read_bytes()), + "main proof facts snapshot differs") + return checker.require_commit(obj["commit"]) + + +def finalize(checker, tag, output): + import release_pipeline as pipeline + + client = GuardedClient(checker.client, checker) + store = GuardedStore(pipeline.Store(client), checker) + # Keep the existing per-release reconciliation, alias, reservation and + # consumer policy code. Guarded reads also cover the empty-tag sweep. + pipeline.finalize_all(client, store, pipeline.Registry(), tag, output) + + +def wait_for_commit(checker, commit, seconds): + deadline = time.monotonic() + seconds + while True: + try: + return checker.require_commit(commit) + except ProofPending: + remaining = deadline - time.monotonic() + if remaining <= 0: + raise + time.sleep(min(15, remaining)) + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__, allow_abbrev=False) + sub = parser.add_subparsers(dest="command", required=True) + command = sub.add_parser("commit", allow_abbrev=False) + command.add_argument("--sha", required=True) + command.add_argument("--wait-seconds", type=int, default=0) + command = sub.add_parser("tag", allow_abbrev=False) + command.add_argument("--tag", required=True) + command.add_argument("--sha", required=True) + command = sub.add_parser("delivery", allow_abbrev=False) + command.add_argument("--tag", required=True) + command = sub.add_parser("facts-source", allow_abbrev=False) + command.add_argument("--source-dir", type=Path, required=True) + command = sub.add_parser("finalize", allow_abbrev=False) + command.add_argument("--tag", default="") + command.add_argument("--output", required=True) + args = parser.parse_args(argv) + checker = MainProof(Client(token=os.environ.get("MAIN_PROOF_TOKEN", os.environ.get("GH_TOKEN", "")))) + try: + if args.command == "commit": + insist(0 <= args.wait_seconds <= 3600, "main proof wait is out of bounds") + wait_for_commit(checker, args.sha, args.wait_seconds) + elif args.command == "tag": + checker.require_tag(args.tag, args.sha) + elif args.command == "delivery": + require_delivery(checker, args.tag) + elif args.command == "facts-source": + require_facts_source(checker, args.source_dir) + else: + finalize(checker, args.tag, args.output) + except (ProofError, Pending, Invalid, ValueError, OSError, KeyError, TypeError): + # Never echo API bodies, credentials, target repositories or paths. + print("::error::release main proof refused; exact main-push CI and facts must be complete and successful", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_release_binding_workflows.py b/tests/test_release_binding_workflows.py index bccce08..7ca595f 100644 --- a/tests/test_release_binding_workflows.py +++ b/tests/test_release_binding_workflows.py @@ -28,6 +28,8 @@ import release_pipeline as pipeline # noqa: E402 import release_contract as contract # noqa: E402 import test_release_workflows as wiring # noqa: E402 +import release_main_proof as main_proof # noqa: E402 +from test_release_main_proof import GitHubProof # noqa: E402 from test_release_binding import (FinalizeClient, MemoryRegistry, MemoryStore, # noqa: E402 ProducerFixture, damage_engine_prerequisite, fixture_manifest) @@ -36,11 +38,113 @@ def workflow(name): return yaml.load((ROOT / ".github/workflows" / name).read_text(), Loader=yaml.BaseLoader) -def write_producer_endpoints(root, client): +def main_proof_endpoints(commit, *, problem=None, manifest=None, tag=None): + """Serialize API responses, never the proof reader's decision.""" + commits = [commit] + if manifest is not None: + commits.append(manifest["facts"]["commit"]) + sources = {} + for index, sha in enumerate(dict.fromkeys(commits)): + api = GitHubProof(sha, run_offset=index * 1000) + if sha == commit and problem is not None: + run = api.runs["facts-validate.yml"][0] + if problem == "missing": + api.runs["facts-validate.yml"] = [] + else: + changes = { + "red": {"conclusion": "failure"}, + "running": {"status": "in_progress", "conclusion": None}, + "skipped": {"conclusion": "skipped"}, + "pr": {"event": "pull_request", "head_branch": "feature"}, + "wrong_sha": {"head_sha": "b" * 40}, + } + if problem not in changes: + raise AssertionError("unknown proof fixture damage") + run.update(changes[problem]) + api.details[run["id"]].update(changes[problem]) + sources[sha] = {field: copy.deepcopy(getattr(api, field)) for field in + ("repo", "compare", "workflows", "runs", "details", "jobs")} + return {"commit": commit, "sources": sources, "manifest": manifest, + "tag": tag or ("v" + manifest["release_version"] if manifest is not None else None)} + + +class MainProofEndpointClient: + """Hub GET transport for shell replays; no proof or publication mocks.""" + + def __init__(self, data): + self.commit, self.tag = data["commit"], data["tag"] + self.sources, self.calls = {}, [] + for commit, fields in data["sources"].items(): + api = GitHubProof(commit) + for field, value in fields.items(): + if field in {"details", "jobs"}: + value = {int(key): item for key, item in value.items()} + setattr(api, field, value) + self.sources[commit] = api + self.active = self.sources[self.commit] + manifest = data["manifest"] + self.store = None + if manifest is not None: + self.store = MemoryStore(manifest) + row = self.store.rows[self.tag] + row["draft"] = False + self.store.put(row, contract.ASSET, contract.canonical(manifest)) + self.store.operations.clear() + + def api(self, route, *, method="GET", data=None): + if method != "GET" or data is not None: + raise AssertionError("proof replay attempted a hub mutation") + self.calls.append(route) + if "/releases/" in route and self.store is not None: + return self.store.api(route) + if "/compare/" in route: + commit = route.split("/compare/", 1)[1].split("...", 1)[0] + self.active = self.sources[commit] + return self.active.api(route) + + def pages(self, route): + self.calls.append(route) + if self.store is None: + raise AssertionError("unmodeled proof release list") + return self.store.pages(route) + + def request(self, url, **kwargs): + if kwargs.get("method", "GET") != "GET" or kwargs.get("data") is not None or self.store is None: + raise AssertionError("proof replay attempted an asset mutation") + self.calls.append(url) + return self.store.request(url, **kwargs) + + def tag_commit(self, repo, tag): + if repo != contract.HUB or tag != self.tag: + raise AssertionError("proof replay selected another tag") + return self.commit + + +def main_proof_fixture_cli(): + """Execute the actual proof CLI using serialized GitHub GET responses.""" + root = Path(os.environ["PRODUCER_FIXTURE_ROOT"]) + data = json.loads((root / "endpoints.json").read_bytes())["main_proof"] + client = MainProofEndpointClient(data) + # Keep the workflow's bounded wait argument. Advancing the fixture clock + # expires unfinished proof without a real sleep or an assumed success. + with patch.object(main_proof, "Client", return_value=client), \ + patch.object(main_proof.time, "monotonic", side_effect=[0, 4001]), \ + patch.object(main_proof.time, "sleep", side_effect=AssertionError("unexpected live proof wait")): + result = main_proof.main(sys.argv[1:]) + (root / "main-proof-result.json").write_bytes(contract.canonical({ + "status": result, "calls": client.calls, + })) + with (root / "git-calls").open("a", encoding="utf-8") as stream: + stream.write("main-proof " + shlex.join(sys.argv[1:]) + "\n") + return result + + +def write_producer_endpoints(root, client, *, proof_problem=None): (root / "endpoints.json").write_bytes(contract.canonical({ "version": str(client.v), "api": client.api_data, "commits": client.commits, "downloads": {url: base64.b64encode(raw).decode("ascii") for url, raw in client.downloads.items()}, + "main_proof": main_proof_endpoints("d" * 40, problem=proof_problem, tag="v" + str(client.v)), })) @@ -60,6 +164,10 @@ def producer_fixture_cli(): """Run the real CLI with serialized public endpoints in a shell replay.""" import release_artifacts as artifacts + if sys.argv[0] == "scripts/release_main_proof.py": + return main_proof_fixture_cli() + if sys.argv[:2] != ["scripts/release_pipeline.py", "producer"]: + raise AssertionError("unexpected producer replay command: " + repr(sys.argv)) root = Path(os.environ["PRODUCER_FIXTURE_ROOT"]) client = producer_fixture_client(root) calls, downloads = [], [] @@ -90,6 +198,8 @@ def publish_fixture_python(): """Execute workflow Python unchanged, replacing only endpoint transport and paths.""" import release_artifacts as artifacts + if sys.argv[0] == "scripts/release_main_proof.py": + return main_proof_fixture_cli() root = Path(os.environ["PRODUCER_FIXTURE_ROOT"]) client = producer_fixture_client(root) @@ -118,36 +228,43 @@ def __new__(cls, *args, **kwargs): class ProducerPreTagTests(unittest.TestCase): - def replay(self, root, client, *, component="engine", retag=False): + def replay(self, root, client, *, component="engine", retag=False, proof_problem=None, release_tail=False, bump_run=None): root.mkdir(parents=True) steps = {row.get("name"): row for row in workflow("handle-upstream.yml")["jobs"]["bump"]["steps"]} completing = steps.get("Verify the completing engine before tagging") self.assertIsNotNone(completing) gate = (steps["Verify the dispatched producer artifacts"] if component == "engine" else completing) bump = steps["Bump VERSION, commit, tag"] - initial = str(client.v) if retag else "1.10.0" + initial = str(client.v) if retag or release_tail else "1.10.0" (root / "VERSION").write_text(initial + "\n", encoding="ascii") - write_producer_endpoints(root, client) + write_producer_endpoints(root, client, proof_problem=proof_problem) + script = bump["run"] if bump_run is None else bump_run + if release_tail: + # Replay the actual fresh-release publication boundary after its + # VERSION/harness commit exists. Harness sync has its own controls; + # this test must distinguish main's base SHA from that final SHA. + script = script[:script.index('if [ "$RETAG" = true ]; then')] + script[script.index('commit="$(git rev-parse HEAD)"'):] bridge_paths = [str(ROOT / "tests"), str(ROOT / "scripts")] bridge = ( f"import sys; sys.path[:0] = {bridge_paths!r}; " "from test_release_binding_workflows import producer_fixture_cli; " "sys.argv = sys.argv[1:]; raise SystemExit(producer_fixture_cli())" ) - # Only git transport is recorded. The selected workflow CLI, sync, - # tagged-source verifier and archive/checksum verifier all run for real. + # Git transport is recorded; both CLIs and all source/archive/proof + # decisions execute unchanged against their serialized endpoint data. wrappers = ( "python3() { command " + shlex.quote(sys.executable) + " -c " + shlex.quote(bridge) + ' "$@"; }\n' 'git() {\n printf \'%s\\n\' "$*" >> "$PRODUCER_FIXTURE_ROOT/git-calls";\n' - ' case "$1" in log) printf \'%s\\n\' "' + "d" * 40 + '";; esac\n}\n' + ' case "$1" in log|rev-parse) printf \'%s\\n\' "' + "d" * 40 + '";; esac\n}\n' ) done = subprocess.run( - ["bash", "--noprofile", "--norc", "-euc", wrappers + gate["run"] + "\n" + bump["run"]], + ["bash", "--noprofile", "--norc", "-euc", wrappers + gate["run"] + "\n" + script], cwd=root, capture_output=True, text=True, env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1", "PRODUCER_FIXTURE_ROOT": str(root), "COMPONENT": component, "VER": str(client.v), "E": str(client.v), "C": str(client.v), "H": str(client.v), "LINE": "pair", "RELEASE": str(client.v), + "next": str(client.v), "RETAG": str(retag).lower(), "GITHUB_STEP_SUMMARY": str(root / "summary")}, ) self.assertNotIn("Traceback", done.stderr) @@ -168,6 +285,9 @@ def assert_control(self, root, component): self.assertEqual(result["calls"], [{"component": "engine", "content_reads": len(ROWS) + 1}]) self.assertEqual(result["content_reads"], len(ROWS) + 1) self.assertEqual(len(result["downloads"]), 4) + proof_result = json.loads((root / "main-proof-result.json").read_bytes()) + self.assertEqual(proof_result["status"], 0) + self.assertTrue(any("head_sha=" + "d" * 40 in route for route in proof_result["calls"])) self.assertTrue(any(call.startswith(f"tag -a v{PARITY_CAPABILITY_FROM} ") for call in git_calls)) self.assertIn(f"push origin v{PARITY_CAPABILITY_FROM}", git_calls) self.assertEqual((root / "VERSION").read_text(), initial + "\n") @@ -210,6 +330,51 @@ def test_bad_engine_prerequisites_refuse_before_version_writes_or_git_on_bump_an self.assertEqual((root / "VERSION").read_text(), initial + "\n") self.assertFalse((root / "absent-publish-bundle").exists()) + def assert_proof_boundary(self, root, done, git_calls, *, allowed, fresh): + result_path = root / "main-proof-result.json" + self.assertTrue(result_path.is_file(), done.stdout + done.stderr) + result = json.loads(result_path.read_bytes()) + self.assertEqual(done.returncode, 0 if allowed else 1, done.stdout + done.stderr) + self.assertEqual(result["status"], done.returncode) + self.assertTrue(result["calls"], "the proof decision must read GitHub identities") + proof_at = next(i for i, call in enumerate(git_calls) if call.startswith("main-proof commit --sha ")) + self.assertIn("--sha " + "d" * 40, git_calls[proof_at]) + if fresh: + self.assertLess(git_calls.index("push origin HEAD:main"), proof_at) + tags = [i for i, call in enumerate(git_calls) if call.startswith("tag -a ")] + if allowed: + self.assertEqual(len(tags), 1) + self.assertLess(proof_at, tags[0]) + else: + self.assertEqual(tags, [], "unproved final commits must never create a tag") + self.assertFalse(any(call.startswith("push origin v") for call in git_calls)) + + def test_real_tag_boundaries_require_final_commit_full_proof_and_detect_removed_guard(self): + from test_parity_source_proof import TaggedEngineFixture + + for fresh in (False, True): + for problem in (None, "missing", "red", "running", "wrong_sha", "pr", "skipped"): + with self.subTest(fresh=fresh, problem=problem), tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) / "tag-boundary" + done, producer, git_calls, initial = self.replay( + root, TaggedEngineFixture(), retag=not fresh, release_tail=fresh, proof_problem=problem) + self.assertEqual(producer["status"], 0, "producer proof must not hide the hub proof control") + self.assert_proof_boundary(root, done, git_calls, allowed=problem is None, fresh=fresh) + self.assertEqual((root / "VERSION").read_text(), initial + "\n") + script = next(step["run"] for step in workflow("handle-upstream.yml")["jobs"]["bump"]["steps"] + if step.get("name") == "Bump VERSION, commit, tag") + guard = 'python3 scripts/release_main_proof.py commit --sha "$commit" --wait-seconds 1800' + self.assertEqual(script.count(guard), 2) + mutant = script.replace(guard, ":") + with tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) / "removed-guard" + done, _, git_calls, _ = self.replay( + root, TaggedEngineFixture(), retag=not fresh, release_tail=fresh, + proof_problem="red", bump_run=mutant) + self.assertEqual(done.returncode, 0, done.stderr) + with self.assertRaises(AssertionError): + self.assert_proof_boundary(root, done, git_calls, allowed=False, fresh=fresh) + def test_cli_refuses_a_tag_moved_between_source_sync_and_archive_pin(self): from parity_bundle import PARITY_CAPABILITY_FROM from test_parity_bundle import ENGINE_REPO, ENGINE_TAG, ROWS @@ -232,9 +397,9 @@ def test_cli_refuses_a_tag_moved_between_source_sync_and_archive_pin(self): class PublishParityGlueTests(unittest.TestCase): - def replay(self, root, client, step, *, tag=None): + def replay(self, root, client, step, *, tag=None, proof_problem=None): root.mkdir(parents=True, exist_ok=True) - write_producer_endpoints(root, client) + write_producer_endpoints(root, client, proof_problem=proof_problem) steps = {row.get("name"): row for row in workflow("publish.yml")["jobs"]["publish"]["steps"]} binding = steps["Bind producer source and package bytes"]["run"] @@ -242,6 +407,11 @@ def replay(self, root, client, step, *, tag=None): script = steps["Sync parity from the immutable engine tag"]["run"] elif step == "bind": script = binding + elif step == "main-proof": + script = steps["Require full main proof before image publication"]["run"] + elif step == "main-proof-reuse": + script = next(row["run"] for row in workflow("publish.yml")["jobs"]["prepare"]["steps"] + if row.get("name") == "Require full main proof before candidate reuse") else: self.assertEqual(step, "bind-heredoc") # Keep the actual redirection and complete heredoc, leaving out @@ -268,11 +438,25 @@ def replay(self, root, client, step, *, tag=None): "PRODUCER_FIXTURE_ROOT": str(root), "TAG": tag or "v" + str(client.v), "E": str(client.v), "C": str(client.v), "H": str(client.v), "HUB_COMMIT": "d" * 40, "RUNNER_TEMP": str(root), + "RELEASE_SHA": "d" * 40, "GITHUB_OUTPUT": str(root / "github-output")}, ) self.assertNotIn("Traceback", done.stderr, done.stdout + done.stderr) return done + def test_image_and_candidate_reuse_shells_execute_exact_commit_proof(self): + from test_parity_source_proof import TaggedEngineFixture + + for step in ("main-proof", "main-proof-reuse"): + for problem in (None, "missing", "red", "running", "wrong_sha", "pr", "skipped"): + with self.subTest(step=step, problem=problem), tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + done = self.replay(root, TaggedEngineFixture(), step, proof_problem=problem) + self.assertEqual(done.returncode, 0 if problem is None else 1, done.stdout + done.stderr) + result = json.loads((root / "main-proof-result.json").read_bytes()) + self.assertEqual(result["status"], done.returncode) + self.assertTrue(any("head_sha=" + "d" * 40 in route for route in result["calls"])) + def assert_control(self, root, client, *, capable=True): from test_parity_bundle import ROWS @@ -437,7 +621,15 @@ def assert_ready_wiring(case, publish, finalizer): named["Image metadata"]["with"]["labels"]) case.assertEqual(publish["jobs"]["notify-consumers"]["uses"], "./.github/workflows/release-finalize.yml") finalize = finalizer["jobs"]["finalize"] - case.assertTrue(any("scripts/release_pipeline.py finalize" in row.get("run", "") for row in finalize["steps"])) + ready = next(row for row in finalize["steps"] if row.get("id") == "ready") + case.assertEqual(ready["run"].splitlines(), [ + "set -euo pipefail", + 'python3 scripts/release_main_proof.py finalize --tag "$TAG" --output "$RUNNER_TEMP/deliveries.json"', + ]) + case.assertNotIn("if", ready) + case.assertNotIn("continue-on-error", ready) + case.assertEqual(finalize["permissions"]["actions"], "read") + case.assertEqual(publish["jobs"]["notify-consumers"]["permissions"]["actions"], "read") dispatch = finalizer["jobs"]["notify-consumers"] case.assertEqual(dispatch["needs"], "finalize") case.assertEqual(dispatch["strategy"]["fail-fast"], "false") @@ -545,7 +737,7 @@ def test_real_decide_shell_reuses_a_draft_candidate_without_an_image_probe(self) def test_negative_controls_detect_removed_runtime_gate_early_latest_and_skipped_fanout(self): original = workflow("publish.yml") - for mutation in ("runtime", "latest", "fanout"): + for mutation in ("runtime", "latest", "fanout", "proof-entry", "proof-softened", "proof-permissions"): obj, finalizer = copy.deepcopy(original), workflow("release-finalize.yml") if mutation == "runtime": obj["jobs"]["publish"]["steps"] = [s for s in obj["jobs"]["publish"]["steps"] @@ -553,8 +745,17 @@ def test_negative_controls_detect_removed_runtime_gate_early_latest_and_skipped_ elif mutation == "latest": step = next(s for s in obj["jobs"]["publish"]["steps"] if s.get("name") == "Image metadata") step["with"]["tags"] += "\ntype=raw,value=latest" - else: + elif mutation == "fanout": finalizer["jobs"]["notify-consumers"]["needs"] = "publish" + else: + finalize = finalizer["jobs"]["finalize"] + ready = next(step for step in finalize["steps"] if step.get("id") == "ready") + if mutation == "proof-entry": + ready["run"] = ready["run"].replace("scripts/release_main_proof.py finalize", "scripts/release_pipeline.py finalize") + elif mutation == "proof-softened": + ready["continue-on-error"] = "true" + else: + finalize["permissions"]["actions"] = "write" with self.subTest(mutation=mutation), self.assertRaises(AssertionError): assert_ready_wiring(self, obj, finalizer) diff --git a/tests/test_release_main_proof.py b/tests/test_release_main_proof.py new file mode 100644 index 0000000..f90da8d --- /dev/null +++ b/tests/test_release_main_proof.py @@ -0,0 +1,488 @@ +#!/usr/bin/env python3 +"""Exact main-push proof refusals and the publication boundaries that consume it. + +Fixtures model GitHub responses independently of the production inventory. No +test transport or proof override is exposed through the production CLI. +""" +from __future__ import annotations + +import copy +import io +import os +from pathlib import Path +import sys +import tempfile +import unittest +from unittest.mock import patch +from urllib.parse import parse_qs, urlsplit + +import yaml + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "scripts")) +import release_main_proof as proof # noqa: E402 +import release_contract as contract # noqa: E402 +import release_pipeline as pipeline # noqa: E402 +from test_release_binding import (FinalizeClient, MemoryRegistry, MemoryStore, # noqa: E402 + fixture_manifest) + +HUB = "pineforge-4pass/pineforge-release" +COMMIT = "a1" * 20 +OTHER = "b2" * 20 +JOBS = { + "python-test.yml": ( + "authz", "changes", "fingerprint-canonical", "release-rules", + "description-renderer", "release-ready-replay", "release/ready", + ), + "facts-validate.yml": ("authz", "validate"), +} + + +class GitHubProof: + """Read-only endpoint fixture; changes to response data decide every result.""" + + def __init__(self, commit=COMMIT, *, run_offset=0): + self.commit = commit + self.repo = {"id": 704, "full_name": HUB, "private": False, "default_branch": "main"} + self.workflows, self.runs, self.details, self.jobs = {}, {}, {}, {} + self.calls = [] + self.compare = {"status": "ahead", "base_commit": {"sha": commit}, + "merge_base_commit": {"sha": commit}} + for index, (filename, names) in enumerate(JOBS.items(), 1): + wid, rid = 100 + index, 900 + index + run_offset + path = ".github/workflows/" + filename + self.workflows[filename] = {"id": wid, "path": path, "state": "active", + "name": filename.removesuffix(".yml")} + run = {"id": rid, "workflow_id": wid, "path": path, + "event": "push", "head_branch": "main", "head_sha": commit, + "repository": copy.deepcopy(self.repo), "head_repository": copy.deepcopy(self.repo), + "pull_requests": [], "status": "completed", "conclusion": "success", + "run_attempt": 2, "run_number": 17 + index + run_offset} + self.runs[filename] = [run] + self.details[rid] = copy.deepcopy(run) + self.jobs[rid] = [ + {"id": rid * 10 + offset, "run_id": rid, "run_attempt": 2, + "head_sha": commit, "name": name, "status": "completed", "conclusion": "success"} + for offset, name in enumerate(names) + ] + self.error = None + + def api(self, route, *, method="GET", data=None): + if method != "GET" or data is not None: + raise AssertionError("proof attempted a write") + self.calls.append(route) + if self.error: + raise self.error + parsed = urlsplit(route) + path, query = parsed.path, parse_qs(parsed.query) + prefix = "repos/" + HUB + if path == prefix: + return copy.deepcopy(self.repo) + if path.startswith(prefix + "/compare/"): + return copy.deepcopy(self.compare) + if path.startswith(prefix + "/actions/workflows/"): + suffix = path.removeprefix(prefix + "/actions/workflows/") + if suffix.endswith("/runs"): + filename = suffix.removesuffix("/runs") + if filename.isdigit(): + filename = next(name for name, row in self.workflows.items() if row["id"] == int(filename)) + if query.get("head_sha") != [self.commit] or query.get("branch") != ["main"] or query.get("event") != ["push"]: + raise AssertionError("proof must request this exact main-push SHA") + return self.page(self.runs[filename], "workflow_runs", query) + return copy.deepcopy(self.workflows[suffix]) + if path.startswith(prefix + "/actions/runs/"): + suffix = path.removeprefix(prefix + "/actions/runs/") + rid = int(suffix.split("/")[0]) + if "/jobs" in suffix: + if suffix != f"{rid}/attempts/{self.details[rid]['run_attempt']}/jobs": + raise AssertionError("proof must read the selected attempt's jobs") + return self.page(self.jobs[rid], "jobs", query) + return copy.deepcopy(self.details[rid]) + raise AssertionError("unmodeled proof endpoint: " + route) + + @staticmethod + def page(rows, key, query): + page = int(query.get("page", ["1"])[0]) + size = int(query.get("per_page", ["100"])[0]) + return {"total_count": len(rows), key: copy.deepcopy(rows[(page - 1) * size:page * size])} + + def tag_commit(self, repo, tag): + if repo != HUB or tag != "v1.6.0": + raise AssertionError("unexpected tag identity") + return self.commit + + +class ReleaseProof: + """Serve independent genuine-shaped proof responses for both hub SHAs.""" + + def __init__(self, release_commit, facts_commit): + self.release_commit = release_commit + commits = dict.fromkeys((release_commit, facts_commit)) + self.sources = {commit: GitHubProof(commit, run_offset=index * 1000) + for index, commit in enumerate(commits)} + self.active = self.sources[release_commit] + + def api(self, route, **kwargs): + if "/compare/" in route: + commit = route.split("/compare/", 1)[1].split("...", 1)[0] + self.active = self.sources[commit] + return self.active.api(route, **kwargs) + + def tag_commit(self, repo, tag): + return self.sources[self.release_commit].tag_commit(repo, tag) + + +class MainProofTests(unittest.TestCase): + def test_full_green_acceptance_uses_both_real_workflows_and_selected_attempts(self): + api = GitHubProof() + result = proof.MainProof(api).require_commit(COMMIT) + self.assertEqual(result["commit"], COMMIT) + self.assertEqual(set(result["runs"]), {"python-test.yml", "facts-validate.yml"}) + self.assertEqual({row["run_id"] for row in result["runs"].values()}, {901, 902}) + self.assertTrue(any("/attempts/2/jobs" in route for route in api.calls)) + + def test_each_missing_workflow_and_each_missing_job_refuses(self): + for filename, names in JOBS.items(): + with self.subTest(workflow=filename): + api = GitHubProof() + api.runs[filename] = [] + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + for name in names: + with self.subTest(workflow=filename, job=name): + api = GitHubProof() + rid = api.runs[filename][0]["id"] + api.jobs[rid] = [job for job in api.jobs[rid] if job["name"] != name] + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_red_running_skipped_and_other_non_success_proof_refuses(self): + states = (("completed", "failure"), ("in_progress", None), ("queued", None), + ("completed", "skipped"), ("completed", "cancelled"), + ("completed", "neutral"), ("completed", "timed_out"), + ("completed", "action_required"), ("completed", None)) + for filename in JOBS: + for status, conclusion in states: + for target in ("run", "job"): + with self.subTest(workflow=filename, status=status, conclusion=conclusion, target=target): + api = GitHubProof() + run = api.runs[filename][0] + rows = (run, api.details[run["id"]]) if target == "run" else (api.jobs[run["id"]][0],) + for row in rows: + row.update(status=status, conclusion=conclusion) + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_wrong_sha_pr_merge_queue_branch_repository_or_workflow_identity_refuses(self): + mutations = ( + {"head_sha": OTHER}, {"event": "pull_request"}, {"event": "merge_group"}, + {"event": "workflow_dispatch"}, {"head_branch": "feature"}, + {"pull_requests": [{"number": 42}]}, {"workflow_id": 999}, + {"path": ".github/workflows/other.yml"}, + {"repository": {"id": 705, "full_name": "example/other", "private": False}}, + {"head_repository": {"id": 705, "full_name": HUB, "private": False}}, + ) + for filename in JOBS: + for change in mutations: + for target in ("list", "detail"): + with self.subTest(workflow=filename, change=change, target=target): + api = GitHubProof() + run = api.runs[filename][0] + (run if target == "list" else api.details[run["id"]]).update(change) + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_old_green_cannot_hide_a_new_failed_or_running_attempt_or_run(self): + for status, conclusion in (("completed", "failure"), ("in_progress", None)): + api = GitHubProof() + old = api.runs["python-test.yml"][0] + latest = {**copy.deepcopy(old), "id": 1901, "run_number": old["run_number"] + 1, + "status": status, "conclusion": conclusion} + api.runs["python-test.yml"].append(latest) + api.details[1901] = copy.deepcopy(latest) + with self.subTest(status=status), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + api = GitHubProof() + api.details[901].update(run_attempt=3, status="in_progress", conclusion=None) + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_run_pagination_cannot_hide_a_new_red_run(self): + api = GitHubProof() + base = api.runs["python-test.yml"][0] + api.runs["python-test.yml"] = [] + for index in range(101): + run = {**copy.deepcopy(base), "id": 3000 + index, "run_number": 100 + index} + if index == 100: + run.update(conclusion="failure") + api.runs["python-test.yml"].append(run) + api.details[run["id"]] = copy.deepcopy(run) + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + self.assertTrue(any("page=2" in route for route in api.calls)) + + def test_duplicate_foreign_stale_or_extra_jobs_refuse(self): + for change in ({"run_id": 900}, {"run_attempt": 1}, {"head_sha": OTHER}, {"id": True}): + api = GitHubProof() + api.jobs[901][0].update(change) + with self.subTest(change=change), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + for extra in ("authz", "unexpected"): + api = GitHubProof() + job = {**api.jobs[901][0], "id": 99999, "name": extra} + api.jobs[901].append(job) + with self.subTest(extra=extra), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_attempt_bound_jobs_do_not_require_the_optional_per_job_attempt_field(self): + api = GitHubProof() + for jobs in api.jobs.values(): + for job in jobs: + job.pop("run_attempt") + result = proof.MainProof(api).require_commit(COMMIT) + self.assertEqual(result["runs"]["python-test.yml"]["run_attempt"], 2) + self.assertTrue(any("/attempts/2/jobs" in route for route in api.calls)) + + def test_wrong_workflow_metadata_main_ancestry_and_transport_errors_refuse(self): + for field, value in (("id", True), ("path", ".github/workflows/copied.yml"), + ("state", "disabled_manually"), ("name", "copied")): + api = GitHubProof() + api.workflows["python-test.yml"][field] = value + with self.subTest(field=field), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + for comparison in ({"status": "diverged"}, {"merge_base_commit": {"sha": OTHER}}): + api = GitHubProof() + api.compare.update(comparison) + with self.subTest(compare=comparison), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + for error in (contract.Pending("missing"), contract.Invalid("HTTP 403"), OSError("transport")): + api = GitHubProof() + api.error = error + with self.subTest(error=type(error).__name__), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_public_hub_identity_cannot_be_replaced(self): + for change in ({"id": True}, {"full_name": "example/other"}, + {"private": True}, {"default_branch": "master"}): + api = GitHubProof() + api.repo.update(change) + with self.subTest(change=change), self.assertRaises(proof.ProofError): + proof.MainProof(api).require_commit(COMMIT) + + def test_tag_must_bind_the_requested_exact_commit(self): + api = GitHubProof() + with self.assertRaises(proof.ProofError): + proof.MainProof(api).require_tag("v1.6.0", OTHER) + self.assertEqual(proof.MainProof(api).require_tag("v1.6.0", COMMIT)["commit"], COMMIT) + + def test_cli_has_no_success_override_and_missing_proof_is_nonzero(self): + api = GitHubProof() + api.runs["facts-validate.yml"] = [] + with patch.object(proof, "Client", return_value=api), patch("sys.stderr", new_callable=io.StringIO): + self.assertNotEqual(proof.main(["commit", "--sha", COMMIT]), 0) + with patch.object(proof, "Client", return_value=GitHubProof()): + self.assertEqual(proof.main(["commit", "--sha", COMMIT]), 0) + with patch("sys.stderr", new_callable=io.StringIO), self.assertRaises(SystemExit): + proof.main(["commit", "--sha", COMMIT, "--allow-missing"]) + + def test_wait_can_only_finish_after_the_missing_run_becomes_full_green(self): + api = GitHubProof() + available = api.runs["facts-validate.yml"] + api.runs["facts-validate.yml"] = [] + + def finish(_seconds): + api.runs["facts-validate.yml"] = available + + with patch.object(proof.time, "sleep", side_effect=finish) as sleep: + result = proof.wait_for_commit(proof.MainProof(api), COMMIT, 60) + self.assertEqual(result["runs"]["facts-validate.yml"]["run_id"], 902) + sleep.assert_called_once() + api = GitHubProof() + api.runs["facts-validate.yml"][0].update(conclusion="failure") + with patch.object(proof.time, "sleep") as sleep, self.assertRaises(proof.ProofError): + proof.wait_for_commit(proof.MainProof(api), COMMIT, 60) + sleep.assert_not_called() + api = GitHubProof() + api.runs["facts-validate.yml"] = [] + with patch.object(proof.time, "monotonic", side_effect=[0, 2]), self.assertRaises(proof.ProofPending): + proof.wait_for_commit(proof.MainProof(api), COMMIT, 1) + + +class PublicationProofTests(unittest.TestCase): + def test_finalizer_refuses_release_or_facts_proof_before_any_publication(self): + for target in ("release", "facts"): + manifest = fixture_manifest() + store, registry = MemoryStore(manifest), MemoryRegistry() + client = FinalizeClient(manifest) + api = ReleaseProof(manifest["hub_commit"], "e" * 40) + api.sources[manifest["hub_commit"] if target == "release" else "e" * 40].runs["facts-validate.yml"] = [] + checker = proof.MainProof(api) + guarded = proof.GuardedStore(store, checker) + guarded_client = proof.GuardedClient(client, checker) + with self.subTest(target=target), patch.object(pipeline, "npm", return_value=manifest["versions"]["codegen"]), self.assertRaises(proof.ProofError): + pipeline.finalize(guarded_client, guarded, registry, store.rows["v1.6.0"]) + self.assertEqual(registry.operations, []) + self.assertEqual(store.operations, []) + + def test_valid_proof_reaches_the_existing_real_finalizer(self): + manifest = fixture_manifest() + store, registry = MemoryStore(manifest), MemoryRegistry() + client = FinalizeClient(manifest) + api = ReleaseProof(manifest["hub_commit"], "e" * 40) + checker = proof.MainProof(api) + with patch.object(pipeline, "npm", return_value=manifest["versions"]["codegen"]): + event = pipeline.finalize(proof.GuardedClient(client, checker), proof.GuardedStore(store, checker), + registry, store.rows["v1.6.0"]) + self.assertEqual(event["hub_commit"], manifest["hub_commit"]) + self.assertTrue(registry.operations) + self.assertFalse(store.rows["v1.6.0"]["draft"]) + + def test_existing_manifest_replay_requires_its_bound_facts_proof(self): + manifest = fixture_manifest() + store, registry = MemoryStore(manifest), MemoryRegistry() + row = store.rows["v1.6.0"] + store.put(row, contract.ASSET, contract.canonical(manifest)) + store.operations.clear() + api = ReleaseProof(manifest["hub_commit"], manifest["facts"]["commit"]) + api.sources[manifest["facts"]["commit"]].runs["facts-validate.yml"] = [] + checker = proof.MainProof(api) + with self.assertRaises(proof.ProofError): + pipeline.finalize(proof.GuardedClient(FinalizeClient(manifest), checker), + proof.GuardedStore(store, checker), registry, row) + self.assertEqual(store.operations, []) + self.assertEqual(registry.operations, []) + + def test_empty_tag_sweep_uses_the_guard_and_exposes_no_delivery_on_refusal(self): + manifest = fixture_manifest() + api = GitHubProof(manifest["hub_commit"]) + api.runs["facts-validate.yml"] = [] + store, registry = MemoryStore(manifest), MemoryRegistry() + env = {"RELEASE_READY_CONSUMERS": "", "RELEASE_READY_EXCLUDE": "offline,hosted,application,web,data,license,compute", + "FACTS_WEB_DISPATCH_ENABLED": "false", "FACTS_LICENSE_DISPATCH_ENABLED": "false", + "GITHUB_RUN_ID": "700", "GITHUB_RUN_ATTEMPT": "1"} + with tempfile.TemporaryDirectory() as directory, patch.dict(os.environ, env), \ + patch.object(pipeline, "Store", return_value=store), \ + patch.object(pipeline, "Registry", return_value=registry), \ + patch.object(pipeline, "report_issue"): + output = Path(directory) / "deliveries.json" + with self.assertRaises(contract.Invalid): + proof.finalize(proof.MainProof(api), "", str(output)) + self.assertEqual(contract.decode(output.read_bytes()), []) + self.assertEqual(store.operations, []) + self.assertEqual(registry.operations, []) + + def test_delivery_requires_both_bound_commits_and_accepts_full_green(self): + for missing in ("release", "facts", None): + manifest = fixture_manifest() + store = MemoryStore(manifest) + row = store.rows["v1.6.0"] + row["draft"] = False + store.put(row, contract.ASSET, contract.canonical(manifest)) + store.operations.clear() + api = ReleaseProof(manifest["hub_commit"], manifest["facts"]["commit"]) + if missing: + commit = manifest["hub_commit"] if missing == "release" else manifest["facts"]["commit"] + api.sources[commit].runs["facts-validate.yml"] = [] + with self.subTest(missing=missing), patch.object(pipeline, "Store", return_value=store), \ + patch.object(store, "get", side_effect=lambda tag: store.rows[tag]): + if missing: + with self.assertRaises(proof.ProofError): + proof.require_delivery(proof.MainProof(api), "v1.6.0") + else: + proof.require_delivery(proof.MainProof(api), "v1.6.0") + self.assertTrue(all(source.calls for source in api.sources.values())) + self.assertEqual(store.operations, []) + + def test_facts_signal_checks_its_snapshot_not_the_event_sha(self): + api = GitHubProof() + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + raw = b'{"example":1}\n' + (root / "facts.json").write_bytes(raw) + (root / "payload.json").write_bytes(contract.canonical({ + "commit": OTHER, "sha256": contract.sha256(raw), "dry_run": False, + })) + with self.assertRaises(proof.ProofError): + proof.require_facts_source(proof.MainProof(api), root) + (root / "payload.json").write_bytes(contract.canonical({ + "commit": COMMIT, "sha256": contract.sha256(raw), "dry_run": False, + })) + self.assertEqual(proof.require_facts_source(proof.MainProof(api), root)["commit"], COMMIT) + + +class ProofWorkflowTests(unittest.TestCase): + def workflow(self, filename): + return yaml.load((ROOT / ".github/workflows" / filename).read_text(), Loader=yaml.BaseLoader) + + def test_inventory_is_the_actual_full_main_push_ci_and_facts_inventory(self): + for filename, names in JOBS.items(): + document = self.workflow(filename) + actual = {job.get("name", key) for key, job in document["jobs"].items()} + self.assertEqual(actual, set(names)) + self.assertEqual(set(proof.WORKFLOWS[filename]), actual) + + def test_both_tag_routes_prove_the_final_commit_after_main_push(self): + steps = self.workflow("handle-upstream.yml")["jobs"]["bump"]["steps"] + run = next(step["run"] for step in steps if step.get("name") == "Bump VERSION, commit, tag") + recovery, fresh = run.split('if [ "$LINE" = pair ]; then', 1) + for body in (recovery, fresh): + self.assertLess(body.index("scripts/release_main_proof.py commit"), body.index("git tag -a")) + self.assertIn('--sha "$commit"', body) + self.assertLess(fresh.index("git push origin HEAD:main"), fresh.index("scripts/release_main_proof.py commit")) + + def test_candidate_reuse_and_new_images_require_proof(self): + jobs = self.workflow("publish.yml")["jobs"] + for name in ("prepare", "publish"): + steps = jobs[name]["steps"] + gates = [step for step in steps if "scripts/release_main_proof.py tag" in step.get("run", "")] + self.assertEqual(len(gates), 1) + self.assertNotIn("if", gates[0]) + self.assertNotIn("continue-on-error", gates[0]) + self.assertEqual(gates[0]["env"]["RELEASE_SHA"], "${{ needs.tag-guard.outputs.sha }}") + self.assertEqual(jobs[name]["permissions"]["actions"], "read") + if name == "prepare": + self.assertLess(steps.index(gates[0]), next(i for i, step in enumerate(steps) if step.get("id") == "candidate")) + else: + pushes = [i for i, step in enumerate(steps) if step.get("with", {}).get("push") == "true"] + self.assertTrue(pushes) + self.assertTrue(all(steps.index(gates[0]) < i for i in pushes)) + self.assertIn("prepare", jobs["publish"]["needs"]) + + def test_every_finalizer_trigger_uses_guarded_candidate_and_facts_reads(self): + doc = self.workflow("release-finalize.yml") + self.assertEqual(set(doc["on"]), {"workflow_call", "workflow_dispatch", "push", "schedule"}) + step = next(step for step in doc["jobs"]["finalize"]["steps"] if step.get("id") == "ready") + self.assertIn("scripts/release_main_proof.py finalize", step["run"]) + self.assertNotIn("continue-on-error", step) + self.assertEqual(doc["jobs"]["finalize"]["permissions"]["actions"], "read") + + def test_release_senders_and_both_facts_roles_require_proof_before_mint(self): + targets = (("release-finalize.yml", "notify-consumers", "delivery"), + ("release-redeliver.yml", "redeliver", "delivery"), + ("facts-fanout.yml", "web", "facts-source"), + ("facts-fanout.yml", "license", "facts-source")) + for filename, name, command in targets: + with self.subTest(workflow=filename, job=name): + steps = self.workflow(filename)["jobs"][name]["steps"] + gate = next(step for step in steps if step.get("id") == "main-proof") + mint = next(step for step in steps if step.get("id") == "app") + self.assertIn("scripts/release_main_proof.py " + command, gate["run"]) + self.assertLess(steps.index(gate), steps.index(mint)) + self.assertNotIn("continue-on-error", gate) + self.assertNotIn("if", gate) + self.assertEqual(gate["env"]["GH_TOKEN"], "${{ github.token }}") + if filename == "facts-fanout.yml": + send = next(step for step in steps if "scripts/facts_fanout.py dispatch" in step.get("run", "")) + self.assertIn("steps.main-proof.outcome == 'success'", send["if"]) + self.assertIn("steps.main-proof.outcome == 'success'", mint["if"]) + + def test_reconciliation_requires_exact_checked_out_main_proof(self): + job = self.workflow("release-reconcile.yml")["jobs"]["producers"] + steps = job["steps"] + gate = next(step for step in steps if step.get("id") == "main-proof") + self.assertIn('commit --sha "$(git rev-parse HEAD)"', gate["run"]) + self.assertLess(steps.index(gate), next(i for i, step in enumerate(steps) if step.get("id") == "app")) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.py index d1277b9..9e619f8 100644 --- a/tests/test_release_workflows.py +++ b/tests/test_release_workflows.py @@ -305,6 +305,7 @@ class ReleaseTriggerWorkflowTest(unittest.TestCase): ' type: string\n' ) PUBLISH_RELEASE_INPUTS = ( + ("Require full main proof before image publication", "TAG"), ("Assert tag matches VERSION", "TAG"), ("Read pins (from the annotated tag message; fallback = the pair version, or resolve latest on 0.x)", "REF"), ("Pairing rule + release channel", "REF"), @@ -407,6 +408,19 @@ def assert_publish(self, text): self.assertEqual((checkouts[0].get("with") or {}).get("fetch-depth"), "0") candidate = next((row for row in steps if row.get("id") == "candidate"), {}) self.assertEqual((candidate.get("env") or {}).get("TAG"), "${{ needs.tag-guard.outputs.tag }}") + for identity, name, tag in ( + ("prepare", "Require full main proof before candidate reuse", "${{ needs.tag-guard.outputs.tag }}"), + ("publish", "Require full main proof before image publication", "${{ env.RELEASE_TAG }}"), + ): + gates = [row for row in jobs[identity]["steps"] if row.get("name") == name] + self.assertEqual(gates, [{ + "name": name, + "env": {"GH_TOKEN": "${{ github.token }}", "TAG": tag, + "RELEASE_SHA": "${{ needs.tag-guard.outputs.sha }}"}, + "run": 'python3 scripts/release_main_proof.py tag --tag "$TAG" --sha "$RELEASE_SHA"', + }]) + self.assertEqual(jobs[identity]["permissions"]["actions"], "read") + self.assertEqual(jobs["notify-consumers"]["permissions"]["actions"], "read") publish_steps = jobs["publish"].get("steps", []) named = {row.get("name"): row for row in publish_steps} self.assertCountEqual( @@ -499,6 +513,7 @@ def assert_no_publish_dispatch(self, text): def assert_handler(self, text): self.assert_no_publish_dispatch(text) wf = self.parse(text) + self.assertEqual(wf.get("permissions"), {"contents": "read", "actions": "read", "issues": "write"}) steps = wf.get("jobs", {}).get("bump", {}).get("steps", []) app = next((row for row in steps if row.get("id") == "app"), {}) self.assertEqual(app.get("with", {}).get("permission-contents"), "write") @@ -522,6 +537,7 @@ def assert_handler(self, text): self.assertLess(steps.index(decide), steps.index(completing)) self.assertLess(steps.index(completing), steps.index(bump)) self.assertEqual(bump.get("env", {}).get("E"), "${{ steps.decide.outputs.engine }}") + self.assertEqual(bump.get("env", {}).get("MAIN_PROOF_TOKEN"), "${{ github.token }}") self.assertEqual(replay.get("if"), "steps.decide.outputs.mode == 'republish'") self.assertEqual(replay.get("env", {}).get("TAG"), "v${{ steps.decide.outputs.cur_ver }}") for step in (replay, bump): @@ -655,7 +671,7 @@ def test_publish_refuses_bad_triggers_and_each_broken_input_boundary_on_real_tex (" tag: ${{ needs.tag-guard.outputs.tag }}\n", "", 1), (" RELEASE_TAG: ${{ needs.prepare.outputs.tag }}\n", "", 1), (" RELEASE_TAG: ${{ needs.prepare.outputs.tag }}", " RELEASE_TAG: ${{ inputs.tag }}", 1), - (" TAG: ${{ needs.tag-guard.outputs.tag }}", " TAG: ${{ inputs.tag }}", 1), + (" TAG: ${{ needs.tag-guard.outputs.tag }}", " TAG: ${{ inputs.tag }}", 2), (" tag: ${{ needs.prepare.outputs.tag }}", " tag: ${{ inputs.tag }}", 1), (" needs: tag-guard\n", "", 1), (" needs: [tag-guard, prepare]", " needs: prepare", 1), @@ -694,6 +710,21 @@ def test_publish_refuses_bad_triggers_and_each_broken_input_boundary_on_real_tex mutant = self.mutate_step(text, "publish", name, before, after) with self.subTest(step=name, variable=variable, replacement=after), self.assertRaises(AssertionError): self.assert_publish(mutant) + for identity, name in ( + ("prepare", "Require full main proof before candidate reuse"), + ("publish", "Require full main proof before image publication"), + ): + for before, after in ( + (" env:\n", " if: false\n env:\n"), + (" env:\n", " continue-on-error: true\n env:\n"), + (" GH_TOKEN: ${{ github.token }}\n", ""), + (" RELEASE_SHA: ${{ needs.tag-guard.outputs.sha }}", " RELEASE_SHA: ${{ github.sha }}"), + (' run: python3 scripts/release_main_proof.py tag --tag "$TAG" --sha "$RELEASE_SHA"\n', + " run: echo ignored proof\n"), + ): + mutant = self.mutate_step(text, identity, name, before, after) + with self.subTest(step=name, mutation=after), self.assertRaises(AssertionError): + self.assert_publish(mutant) parity_name = "Sync parity from the immutable engine tag" for before, after in ( (" E: ${{ steps.pins.outputs.engine }}\n", ""), @@ -797,6 +828,11 @@ def test_handler_pin_refuses_dispatch_permissions_tokens_or_broken_operator_noti mutant = self.mutate_step(text, "bump", name, before, after) with self.subTest(step=name, boundary="engine input", replacement=after), self.assertRaises(AssertionError): self.assert_handler(mutant) + for after in ("", " MAIN_PROOF_TOKEN: ${{ steps.app.outputs.token }}\n"): + mutant = self.mutate_step(text, "bump", self.BUMP, + " MAIN_PROOF_TOKEN: ${{ github.token }}\n", after) + with self.subTest(boundary="read-only hub proof token", replacement=after), self.assertRaises(AssertionError): + self.assert_handler(mutant) completing_if = " if: steps.decide.outputs.mode == 'bump' && steps.in.outputs.component != 'engine'\n" for before, after in ( (completing_if, ""), @@ -1111,7 +1147,7 @@ def assert_asset_read_token_wiring(self, workflow): self.assertEqual(workflow.get("permissions"), {"contents": "read"}) job = workflow["jobs"]["publish"] self.assertEqual(job.get("environment"), "release-automation") - self.assertEqual(job.get("permissions"), {"contents": "write", "packages": "write"}) + self.assertEqual(job.get("permissions"), {"contents": "write", "packages": "write", "actions": "read"}) steps = job["steps"] mints = [step for step in steps if step.get("uses", "").startswith("actions/create-github-app-token@")] @@ -2033,7 +2069,7 @@ def test_compute_configuration_error_is_reported_after_consumer_delivery(self): ready = next(step for step in finalize["steps"] if step.get("id") == "ready") self.assertEqual(ready["run"].splitlines(), [ "set -euo pipefail", - 'python3 scripts/release_pipeline.py finalize --tag "$TAG" --output "$RUNNER_TEMP/deliveries.json"', + 'python3 scripts/release_main_proof.py finalize --tag "$TAG" --output "$RUNNER_TEMP/deliveries.json"', ]) output = next(step for step in finalize["steps"] if step.get("id") == "delivery-output") self.assertEqual(output["if"], "${{ always() }}") @@ -2143,15 +2179,19 @@ def test_public_eligibility_is_checked_before_target_token_mint(self): self.assertLess(steps.index(checkout), steps.index(check)) self.assertLess(steps.index(check), steps.index(mint)) self.assertLess(steps.index(mint), steps.index(send)) - # Both pre-mint checks stay, in this order: authorization, this public eligibility check, - # then the repository guard (the first step that resolves a target secret), then the mint. + # Authorization and public eligibility precede main proof, then the + # repository guard (the first target-secret read) and the token mint. authorization = next(step for step in steps if step.get("name") == "Authorize consumer and pair before token mint") + proof = next(step for step in steps if step.get("id") == "main-proof") guard = next(step for step in steps if step.get("name") == "Require one configured consumer repository") self.assertLess(steps.index(checkout), steps.index(authorization)) self.assertLess(steps.index(authorization), steps.index(check)) - self.assertLess(steps.index(check), steps.index(guard)) + self.assertLess(steps.index(check), steps.index(proof)) + self.assertLess(steps.index(proof), steps.index(guard)) self.assertLess(steps.index(guard), steps.index(mint)) + self.assertEqual(proof["env"], {"GH_TOKEN": "${{ github.token }}", "TAG": "${{ inputs.tag }}"}) + self.assertEqual(proof["run"], 'python3 scripts/release_main_proof.py delivery --tag "$TAG"') self.assertNotIn("secrets.", json.dumps(steps[:steps.index(check) + 1]), "a step resolves a secret before authorization and eligibility complete") self.assertEqual(check["env"], { @@ -2162,7 +2202,7 @@ def test_public_eligibility_is_checked_before_target_token_mint(self): }) self.assertEqual(check["run"], 'python3 scripts/release_pipeline.py redeliver-check --tag "$TAG" --consumer "$CONSUMER"\n') - for step in (check, mint, send): + for step in (check, proof, mint, send): self.assertNotIn("if", step) self.assertNotIn("continue-on-error", step) @@ -2195,16 +2235,46 @@ def secret_paths(node, path): self.assertNotIn("if", step, "target secrets require successful authorization") self.assertNotIn("continue-on-error", step, "authorization failure must stop the job") - def authorization_flow(self, steps, *, enabled="compute", first="1.6.0", tag="v1.6.0", consumer="compute"): + def proof_shell(self, script, environment, tag, problem): + from test_release_binding import fixture_manifest + from test_release_binding_workflows import main_proof_endpoints + + manifest = fixture_manifest(tag.removeprefix("v")) + with tempfile.TemporaryDirectory() as temporary: + root = Path(temporary) + (root / "endpoints.json").write_text(json.dumps({"main_proof": main_proof_endpoints( + manifest["hub_commit"], problem=problem, manifest=manifest, tag=tag)})) + paths = [str(REPO / "tests"), str(REPO / "scripts")] + bridge = ( + f"import sys; sys.path[:0] = {paths!r}; " + "from test_release_binding_workflows import main_proof_fixture_cli; " + "sys.argv = sys.argv[1:]; raise SystemExit(main_proof_fixture_cli())" + ) + wrapper = ("python3() { command " + shlex.quote(sys.executable) + " -c " + + shlex.quote(bridge) + ' "$@"; }\n') + result = subprocess.run( + ["bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", wrapper + script], + cwd=REPO, env={**environment, "PRODUCER_FIXTURE_ROOT": str(root)}, + capture_output=True, text=True, timeout=30, + ) + self.assertNotIn("Traceback", result.stderr, result.stdout + result.stderr) + recorded = json.loads((root / "main-proof-result.json").read_bytes()) + self.assertEqual(recorded["status"], result.returncode) + self.assertTrue(any("/actions/workflows/" in route for route in recorded["calls"])) + return result + + def authorization_flow(self, steps, *, enabled="compute", first="1.6.0", tag="v1.6.0", consumer="compute", proof_problem=None): """CI only: execute actual guards; count reached mint/dispatch boundaries. The public eligibility step reads the live hub, so this walk counts it instead of running it: test_release_redeliver.RedeliverTest.workflow_before_target_mint runs that same step against - its fake hub. A mint reached before that step fails here, so both pre-mint checks stay in line. + its fake hub. The main proof shell executes against serialized hub GETs. + A mint before either check fails; no proof decision is assumed green. """ follows = (".github/workflows/release-redeliver.yml", "scripts/release_pipeline.py", "scripts/release_contract.py", "scripts/release_pair.py", - "scripts/release_artifacts.py", "scripts/release_sources.py", os.devnull) + "scripts/release_artifacts.py", "scripts/release_sources.py", + "scripts/release_main_proof.py", os.devnull) forbidden = ("/.config/zsh/keys", "/.ssh", "/.aws", "/.codex", "/.config/pineforge") for name in follows: path = str(REPO / name) @@ -2219,6 +2289,7 @@ def authorization_flow(self, steps, *, enabled="compute", first="1.6.0", tag="v1 "${{ vars.RELEASE_READY_EXCLUDE }}": ",".join( role for role in contract.ROLES if role not in enabled.split(",")), "${{ vars.RELEASE_COMPUTE_FIRST_PAIR }}": first, + "${{ github.token }}": "test-hub-read", } for step in steps: target = step.get("env", {}).get("TARGET_REPOSITORY") @@ -2228,13 +2299,14 @@ def authorization_flow(self, steps, *, enabled="compute", first="1.6.0", tag="v1 "TARGET_REPOSITORY": "configured-target", "GITHUB_OUTPUT": os.devnull} checkout = next(i for i, step in enumerate(steps) if step.get("uses", "").startswith("actions/checkout@")) - mints, dispatches, eligibility_checks, results = 0, 0, 0, [] + mints, dispatches, eligibility_checks, proof_checks, results = 0, 0, 0, 0, [] for step in steps[checkout + 1:]: self.assertNotIn("if", step, "authorization and token steps must use the default success guard") self.assertNotIn("continue-on-error", step, "a failed authorization must stop later steps") self.assertEqual(step.get("shell", "bash"), "bash") if step.get("uses", "").startswith("actions/create-github-app-token@"): self.assertEqual(eligibility_checks, 1, "the public eligibility check must precede the token mint") + self.assertEqual(proof_checks, 1, "full main proof must precede the token mint") mints += 1 continue if "release_pipeline.py redeliver " in step.get("run", ""): @@ -2254,10 +2326,15 @@ def authorization_flow(self, steps, *, enabled="compute", first="1.6.0", tag="v1 self.assertIn(value, context, "unexpected workflow control context") value = context[value] step_env[key] = value - result = subprocess.run( - ["bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", script], - cwd=REPO, env=step_env, capture_output=True, text=True, timeout=30, - ) + if "scripts/release_main_proof.py delivery" in script: + self.assertEqual(eligibility_checks, 1, "eligibility must precede hub proof reads") + result = self.proof_shell(script, step_env, tag, proof_problem) + proof_checks += 1 + else: + result = subprocess.run( + ["bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", script], + cwd=REPO, env=step_env, capture_output=True, text=True, timeout=30, + ) results.append(result) if result.returncode: return mints, dispatches, results @@ -2304,6 +2381,27 @@ def test_authorization_crash_stops_the_sequence_and_retains_its_exit(self): self.assertEqual(results[-1].returncode, 1) self.assertIn("RuntimeError: deliberate authorization crash", results[-1].stderr) + def test_redelivery_main_proof_refuses_before_mint_and_detects_missing_or_softened_gate(self): + original = _workflow("release-redeliver.yml")["jobs"]["redeliver"]["steps"] + for problem in (None, "missing", "red", "running", "wrong_sha", "pr", "skipped"): + with self.subTest(problem=problem): + mints, dispatches, results = self.authorization_flow(original, proof_problem=problem) + self.assertEqual((mints, dispatches), (1, 1) if problem is None else (0, 0)) + self.assertEqual(results[-1].returncode, 0 if problem is None else 1) + for mutation in ("removed", "late", "conditional", "softened"): + steps = copy.deepcopy(original) + gate = next(step for step in steps if step.get("id") == "main-proof") + if mutation in {"removed", "late"}: + steps.remove(gate) + if mutation == "late": + steps.append(gate) + elif mutation == "conditional": + gate["if"] = "success()" + else: + gate["continue-on-error"] = "true" + with self.subTest(mutation=mutation), self.assertRaises(AssertionError): + self.authorization_flow(steps) + def test_manual_inputs_protected_single_job_and_serialized_permissions(self): """Mutation: delete the redeliver job's main-ref if.""" wf = _workflow("release-redeliver.yml") @@ -2325,7 +2423,7 @@ def test_manual_inputs_protected_single_job_and_serialized_permissions(self): self.assertNotIn("needs", job) self.assertEqual(job["runs-on"], "ubuntu-latest") self.assertEqual(job["environment"], "release-automation") - self.assertEqual(job["permissions"], {"contents": "write", "issues": "write"}) + self.assertEqual(job["permissions"], {"contents": "write", "issues": "write", "actions": "read"}) self.assertEqual(job["concurrency"], { "group": "release-delivery-${{ inputs.consumer }}-${{ inputs.tag }}", "cancel-in-progress": "false", From ba58871dd9086382f7370a9978b75d595848fb74 Mon Sep 17 00:00:00 2001 From: luisleo526 <20812494+luisleo526@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:14:43 +0800 Subject: [PATCH 2/2] Keep sweeps and facts pushes working behind the main-proof barrier The exact-commit main proof made every finalize sweep re-prove every release that has a candidate, so a release that predates today's CI job list could never pass and failed the whole sweep, dropping all consumer deliveries. A candidate whose proof is refused but that is already ready now takes the existing historical path (no alias, publish or delivery for it); a refused candidate that is not ready still fails. Also: the report-only facts freshness read is no longer proved (the manifest write already proves the bound facts commit before any alias, publish or ready step); a pending proof is reported as pending instead of failed; facts-source waits up to 30 minutes on a push for its own commit's CI, like the commit check; and the retag hint no longer promises a retag that the barrier refuses, with the manual recovery for a red release commit documented. Tests: new sweep, freshness, pending and facts-source wait tests in tests/test_release_main_proof.py fail before this change and pass with it. --- .github/workflows/facts-fanout.yml | 6 +- docs/release-main-proof.md | 42 ++++-- scripts/release_main_proof.py | 40 +++--- scripts/release_pair.py | 16 ++- tests/test_release_main_proof.py | 206 ++++++++++++++++++++++++++++- 5 files changed, 267 insertions(+), 43 deletions(-) diff --git a/.github/workflows/facts-fanout.yml b/.github/workflows/facts-fanout.yml index 1e005c4..c29815f 100644 --- a/.github/workflows/facts-fanout.yml +++ b/.github/workflows/facts-fanout.yml @@ -58,7 +58,8 @@ jobs: id: main-proof env: GH_TOKEN: ${{ github.token }} - run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" + WAIT_SECONDS: ${{ github.event_name == 'push' && '1800' || '0' }} + run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" --wait-seconds "$WAIT_SECONDS" - name: Mint consumer token id: app if: >- @@ -132,7 +133,8 @@ jobs: id: main-proof env: GH_TOKEN: ${{ github.token }} - run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" + WAIT_SECONDS: ${{ github.event_name == 'push' && '1800' || '0' }} + run: python3 scripts/release_main_proof.py facts-source --source-dir "$RUNNER_TEMP/fanout-source" --wait-seconds "$WAIT_SECONDS" - name: Mint consumer token id: app if: >- diff --git a/docs/release-main-proof.md b/docs/release-main-proof.md index 39cd244..22913d1 100644 --- a/docs/release-main-proof.md +++ b/docs/release-main-proof.md @@ -41,19 +41,45 @@ the optional per-job attempt field, it must match that endpoint's attempt. | Producer reconciliation | Prove the checked-out main SHA before replaying producer events; the handler separately proves the release commit it creates. | `finalize` in the new helper calls the existing `release_pipeline.finalize_all` -with guarded storage and source reads. This covers reusable, manual, scheduled, +with guarded candidate and manifest storage. This covers reusable, manual, scheduled, and facts-push finalization, including an empty-tag candidate sweep. It avoids a preflight over one candidate list followed by publication from a newly selected list. Facts may arrive in a later main commit than the release commit, so each -of those exact SHAs requires its own full CI and facts proof. Historical rows +of those exact SHAs requires its own full CI and facts proof. The manifest's +bound facts commit is proved before its immutable write, ahead of every alias, +publication and readiness step; replay proves the existing manifest's bound +commit too. The latest facts read used only for a freshness report needs no +publication proof. + +When candidate proof is refused for a row that already has `release-ready.json`, +the finalizer leaves that row as historical data: it performs no alias, +publication or delivery work for it, and continues the sweep. An unprovable row +without readiness remains pending or failed as appropriate. Historical rows read only to compare versions do not acquire publication authority. -The handler waits up to 1,800 seconds for missing or unfinished runs, without -dispatching or rerunning CI. Failed proof stops immediately. If proof never -becomes complete, the main commit remains available and no release tag is -created. Other routes refuse unavailable proof at their normal wake-up; their -existing recovery triggers remain responsible for subsequent attempts. Old -releases without the required proof receive no exemption. +The handler and facts-fanout push jobs wait up to 1,800 seconds for missing or +unfinished runs, without dispatching or rerunning CI. The `commit` and +`facts-source` commands accept `--wait-seconds` (default zero, maximum 3,600). +Failed proof stops immediately; an expired wait still refuses publication. +The finalizer reports unfinished proof as readiness pending and retries at its +next normal wake-up. Other routes refuse unavailable proof at their normal +wake-up; their existing recovery triggers remain responsible for subsequent +attempts. + +## Recovering a release commit with failed CI + +The handler pushes the VERSION bump before proving that exact release commit. +If its CI is red, no tag is created and VERSION can remain ahead of the landed +pair. Sending the same event again still checks the original release commit; +a later green main commit cannot authorize its missing tag. + +A maintainer must manually revert the untagged VERSION bump on `main` to the +landed release version, then send the upstream event again. Use the normal +reviewed main change process and resolve the CI failure before replaying the +event. The handler can then create a fresh release commit, whose own complete +main-push CI and facts proof must pass before tagging. Leave existing tags and +release assets intact. If proof was only pending, retry the event after that +original commit's proof passes; the retag route still selects that commit. The workflows grant their hub token `actions: read` for proof reads; consumer tokens retain their existing scopes. Proof snapshots are cached only within diff --git a/scripts/release_main_proof.py b/scripts/release_main_proof.py index 6603c20..d3c462f 100644 --- a/scripts/release_main_proof.py +++ b/scripts/release_main_proof.py @@ -2,8 +2,8 @@ """Require this hub's complete successful main-push CI on an exact commit. The proof reader only GETs public hub identities. Publication still uses the -existing release pipeline; its candidate and facts reads are guarded here so -scheduled reconciliation cannot select an unproved commit after a preflight. +existing release pipeline; candidate reads and manifest storage are guarded +here so scheduled reconciliation cannot publish an unproved bound commit. """ from __future__ import annotations @@ -34,8 +34,8 @@ class ProofError(Invalid): """No publication is authorized by this proof.""" -class ProofPending(ProofError): - """The handler may wait for a missing or unfinished main-push run.""" +class ProofPending(ProofError, Pending): + """Wait or retry later for a missing or unfinished main-push run.""" def insist(condition, message): @@ -192,21 +192,6 @@ def require_tag(self, tag, expected_sha=None): return self.require_commit(commit) -class GuardedClient: - """Prove the facts commit actually selected by the existing finalizer.""" - - def __init__(self, client, checker): - self.client, self.checker = client, checker - - def __getattr__(self, name): - return getattr(self.client, name) - - def file(self, repo, commit, path): - if repo == HUB and path == "facts/facts.json": - self.checker.require_commit(commit) - return self.client.file(repo, commit, path) - - class GuardedStore: """Check each candidate before the real pipeline can publish its manifest.""" @@ -228,7 +213,12 @@ def read(self, row, name): if raw is not None and name == CANDIDATE: candidate = validate_candidate(decode(raw)) insist(row["tag_name"] == "v" + candidate["release_version"], "main proof candidate tag differs") - self.checker.require_tag(row["tag_name"], candidate["hub_commit"]) + try: + self.checker.require_tag(row["tag_name"], candidate["hub_commit"]) + except ProofError: + if self.store.read(row, "release-ready.json") is not None: + return None # Historical readiness authorizes no new work. + raise self.candidates.add(row["tag_name"]) elif raw is not None and name == ASSET and row["tag_name"] in self.candidates: # Existing manifests can replay aliases too; they need proof for @@ -255,18 +245,18 @@ def require_delivery(checker, tag): guarded.manifest(row, raw) -def require_facts_source(checker, directory): +def require_facts_source(checker, directory, wait_seconds=0): obj = decode((directory / "payload.json").read_bytes()) keys(obj, ("commit", "sha256", "dry_run")) insist(type(obj["dry_run"]) is bool and obj["sha256"] == sha256((directory / "facts.json").read_bytes()), "main proof facts snapshot differs") - return checker.require_commit(obj["commit"]) + return wait_for_commit(checker, obj["commit"], wait_seconds) def finalize(checker, tag, output): import release_pipeline as pipeline - client = GuardedClient(checker.client, checker) + client = checker.client store = GuardedStore(pipeline.Store(client), checker) # Keep the existing per-release reconciliation, alias, reservation and # consumer policy code. Guarded reads also cover the empty-tag sweep. @@ -298,6 +288,7 @@ def main(argv=None): command.add_argument("--tag", required=True) command = sub.add_parser("facts-source", allow_abbrev=False) command.add_argument("--source-dir", type=Path, required=True) + command.add_argument("--wait-seconds", type=int, default=0) command = sub.add_parser("finalize", allow_abbrev=False) command.add_argument("--tag", default="") command.add_argument("--output", required=True) @@ -312,7 +303,8 @@ def main(argv=None): elif args.command == "delivery": require_delivery(checker, args.tag) elif args.command == "facts-source": - require_facts_source(checker, args.source_dir) + insist(0 <= args.wait_seconds <= 3600, "main proof wait is out of bounds") + require_facts_source(checker, args.source_dir, args.wait_seconds) else: finalize(checker, args.tag, args.output) except (ProofError, Pending, Invalid, ValueError, OSError, KeyError, TypeError): diff --git a/scripts/release_pair.py b/scripts/release_pair.py index 4f65155..9d6f7cb 100755 --- a/scripts/release_pair.py +++ b/scripts/release_pair.py @@ -217,10 +217,14 @@ def _decide_triple(component: str, v: Version, ep: Version, cp: Version, if landed_pair and cur != ep: raise RuleError(f"VERSION {cur} does not match the landed pair {landed}; " f"if main carries its release commit without its tag, send an " - f"event for {cur} again to tag it") + f"event for {cur} again only after that exact release commit's " + "main-push CI and facts proof pass; for red CI, see manual " + "recovery in docs/release-main-proof.md") if not landed_pair and (cur.line != "legacy" or cur.prerelease): raise RuleError(f"VERSION {cur} has no release tag: a pair release is half-done; " - f"send an event for {cur} again to tag it") + f"send an event for {cur} again only after that exact release " + "commit's main-push CI and facts proof pass; for red CI, see " + "manual recovery in docs/release-main-proof.md") out = {"line": v.line, "eprev": str(ep), "cprev": str(cp), "hprev": str(hp) if hp else "", "release": "", "prerelease": _flag(v.prerelease), "awaiting": "", "retag": _flag(retag)} if not missing: @@ -345,11 +349,15 @@ def same_or_bump(e: Version, c: Version) -> str: if landed_pair and cur != ep: raise RuleError(f"VERSION {cur} does not match the landed pair engine {ep} + " f"codegen {cp}; if main carries a release commit for {cur} without " - f"its tag, send an event for {cur} again to tag it") + f"its tag, send an event for {cur} again only after that exact " + "release commit's main-push CI and facts proof pass; for red CI, " + "see manual recovery in docs/release-main-proof.md") if not landed_pair and (cur.line != "legacy" or cur.prerelease): raise RuleError(f"VERSION {cur} has no release tag: a pair release is half-done " f"(main carries its commit, tag v{cur} is missing); send an " - f"event for {cur} again to tag it") + f"event for {cur} again only after that exact release commit's " + "main-push CI and facts proof pass; for red CI, see manual " + "recovery in docs/release-main-proof.md") if completes: out.update(mode="bump" if retag else same_or_bump(v, v), engine=str(v), codegen=str(v), release=str(v), prerelease=_flag(v.prerelease), retag=_flag(retag)) diff --git a/tests/test_release_main_proof.py b/tests/test_release_main_proof.py index f90da8d..ed17f5d 100644 --- a/tests/test_release_main_proof.py +++ b/tests/test_release_main_proof.py @@ -132,6 +132,37 @@ def tag_commit(self, repo, tag): return self.sources[self.release_commit].tag_commit(repo, tag) +class FinalizerProofClient(FinalizeClient): + """Serve finalizer sources and proof endpoints through the same client.""" + + def __init__(self, *manifests): + super().__init__(*manifests) + self.proofs = ReleaseProof(manifests[0]["hub_commit"], manifests[0]["facts"]["commit"]) + for manifest in manifests[1:]: + for commit in (manifest["hub_commit"], manifest["facts"]["commit"]): + if commit not in self.proofs.sources: + self.proofs.sources[commit] = GitHubProof(commit, run_offset=1000 * len(self.proofs.sources)) + self.latest_facts_commit = manifests[0]["facts"]["commit"] + self.file_reads = [] + + def api(self, route, **kwargs): + prefix = "repos/" + HUB + if route == prefix or route.startswith((prefix + "/compare/", prefix + "/actions/")): + return self.proofs.api(route, **kwargs) + if route == prefix + "/git/ref/heads/main": + return {"object": {"sha": self.latest_facts_commit}} + result = super().api(route, **kwargs) + if route == prefix + "/commits?path=facts/facts.json&sha=main&per_page=1": + result[0]["sha"] = self.latest_facts_commit + return result + + def file(self, repo, commit, path): + self.file_reads.append((repo, commit, path)) + if (repo, commit, path) == (HUB, self.latest_facts_commit, "facts/facts.json"): + return contract.canonical(self.facts) + return super().file(repo, commit, path) + + class MainProofTests(unittest.TestCase): def test_full_green_acceptance_uses_both_real_workflows_and_selected_attempts(self): api = GitHubProof() @@ -318,9 +349,8 @@ def test_finalizer_refuses_release_or_facts_proof_before_any_publication(self): api.sources[manifest["hub_commit"] if target == "release" else "e" * 40].runs["facts-validate.yml"] = [] checker = proof.MainProof(api) guarded = proof.GuardedStore(store, checker) - guarded_client = proof.GuardedClient(client, checker) with self.subTest(target=target), patch.object(pipeline, "npm", return_value=manifest["versions"]["codegen"]), self.assertRaises(proof.ProofError): - pipeline.finalize(guarded_client, guarded, registry, store.rows["v1.6.0"]) + pipeline.finalize(client, guarded, registry, store.rows["v1.6.0"]) self.assertEqual(registry.operations, []) self.assertEqual(store.operations, []) @@ -331,7 +361,7 @@ def test_valid_proof_reaches_the_existing_real_finalizer(self): api = ReleaseProof(manifest["hub_commit"], "e" * 40) checker = proof.MainProof(api) with patch.object(pipeline, "npm", return_value=manifest["versions"]["codegen"]): - event = pipeline.finalize(proof.GuardedClient(client, checker), proof.GuardedStore(store, checker), + event = pipeline.finalize(client, proof.GuardedStore(store, checker), registry, store.rows["v1.6.0"]) self.assertEqual(event["hub_commit"], manifest["hub_commit"]) self.assertTrue(registry.operations) @@ -347,7 +377,7 @@ def test_existing_manifest_replay_requires_its_bound_facts_proof(self): api.sources[manifest["facts"]["commit"]].runs["facts-validate.yml"] = [] checker = proof.MainProof(api) with self.assertRaises(proof.ProofError): - pipeline.finalize(proof.GuardedClient(FinalizeClient(manifest), checker), + pipeline.finalize(FinalizeClient(manifest), proof.GuardedStore(store, checker), registry, row) self.assertEqual(store.operations, []) self.assertEqual(registry.operations, []) @@ -355,7 +385,7 @@ def test_existing_manifest_replay_requires_its_bound_facts_proof(self): def test_empty_tag_sweep_uses_the_guard_and_exposes_no_delivery_on_refusal(self): manifest = fixture_manifest() api = GitHubProof(manifest["hub_commit"]) - api.runs["facts-validate.yml"] = [] + api.runs["facts-validate.yml"][0].update(conclusion="failure") store, registry = MemoryStore(manifest), MemoryRegistry() env = {"RELEASE_READY_CONSUMERS": "", "RELEASE_READY_EXCLUDE": "offline,hosted,application,web,data,license,compute", "FACTS_WEB_DISPATCH_ENABLED": "false", "FACTS_LICENSE_DISPATCH_ENABLED": "false", @@ -409,6 +439,164 @@ def test_facts_signal_checks_its_snapshot_not_the_event_sha(self): })) self.assertEqual(proof.require_facts_source(proof.MainProof(api), root)["commit"], COMMIT) + def test_facts_source_wait_requires_completion_before_its_deadline(self): + for outcome in ("completed", "pending", "failed"): + with self.subTest(outcome=outcome), tempfile.TemporaryDirectory() as directory: + root = Path(directory) + raw = b'{"example":1}\n' + (root / "facts.json").write_bytes(raw) + (root / "payload.json").write_bytes(contract.canonical({ + "commit": OTHER, "sha256": contract.sha256(raw), "dry_run": False, + })) + api = GitHubProof(OTHER) + run = api.runs["facts-validate.yml"][0] + for row in (run, api.details[run["id"]]): + row.update(status="completed" if outcome == "failed" else "in_progress", + conclusion="failure" if outcome == "failed" else None) + elapsed = [0] + + def tick(seconds): + elapsed[0] += seconds + if outcome == "completed": + for row in (run, api.details[run["id"]]): + row.update(status="completed", conclusion="success") + + with patch.object(proof, "Client", return_value=api), \ + patch.object(proof.time, "monotonic", side_effect=lambda: elapsed[0]), \ + patch.object(proof.time, "sleep", side_effect=tick) as sleep, \ + patch("sys.stderr", new_callable=io.StringIO): + result = proof.main(["facts-source", "--source-dir", str(root), "--wait-seconds", "30"]) + self.assertEqual(result, 0 if outcome == "completed" else 1) + self.assertTrue(any("head_sha=" + OTHER in route for route in api.calls)) + if outcome == "completed": + sleep.assert_called_once_with(15) + self.assertTrue(any(f"/actions/runs/{run['id']}/attempts/2/jobs" in route for route in api.calls)) + elif outcome == "pending": + self.assertEqual(elapsed[0], 30) + self.assertEqual(sleep.call_count, 2) + else: + sleep.assert_not_called() + + +class FinalizerSweepTests(unittest.TestCase): + def sweep(self, client, store, registry, *, consumers=("offline",)): + env = { + "RELEASE_READY_CONSUMERS": ",".join(consumers), + "RELEASE_READY_EXCLUDE": ",".join(role for role in contract.ROLES if role not in consumers), + "FACTS_WEB_DISPATCH_ENABLED": "false", "FACTS_LICENSE_DISPATCH_ENABLED": "false", + "GITHUB_RUN_ID": "700", "GITHUB_RUN_ATTEMPT": "1", + } + store_type = pipeline.Store + # MemoryStore.get still exercises the real Store's lookup contract. + with tempfile.TemporaryDirectory() as directory, patch.dict(os.environ, env, clear=True), \ + patch.object(proof, "Client", return_value=client), \ + patch.object(pipeline, "Store", side_effect=lambda source: store_type(source) if source is store else store), \ + patch.object(pipeline, "Registry", return_value=registry), \ + patch.object(pipeline, "age_minutes", return_value=0), \ + patch.object(pipeline, "report_issue") as report, \ + patch("sys.stderr", new_callable=io.StringIO): + output = Path(directory) / "deliveries.json" + result = proof.main(["finalize", "--output", str(output)]) + return result, contract.decode(output.read_bytes()), report.call_args_list + + def test_sweep_skips_refused_ready_history_but_fails_unready_history(self): + cases = (("inventory", True), ("missing-facts-run", True), ("inventory", False)) + for refusal, ready in cases: + with self.subTest(refusal=refusal, ready=ready): + current, old = fixture_manifest(), fixture_manifest("1.5.9") + store, registry = MemoryStore(current, old), MemoryRegistry() + current_row, old_row = store.rows["v1.6.0"], store.rows["v1.5.9"] + store.put(current_row, contract.ASSET, contract.canonical(current)) + if ready: + old_row["draft"] = False + store.put(old_row, contract.ASSET, contract.canonical(old)) + store.put(old_row, "release-ready.json", contract.canonical({ + "event_id": contract.payload(contract.canonical(old))["event_id"], + "timestamp": "2026-10-16T00:00:00Z", + })) + old_before = copy.deepcopy(old_row) + old_assets = {name: raw for (tag, name), raw in store.assets.items() if tag == old_row["tag_name"]} + store.operations.clear() + client = FinalizerProofClient(current, old) + historical = client.proofs.sources[old["hub_commit"]] + if refusal == "inventory": + rid = historical.runs["python-test.yml"][0]["id"] + historical.jobs[rid] = [job for job in historical.jobs[rid] if job["name"] != "release-ready-replay"] + else: + historical.runs["facts-validate.yml"] = [] + + result, deliveries, reports = self.sweep(client, store, registry) + self.assertEqual(result, 0 if ready else 1) + self.assertEqual(deliveries, [{"consumer": "offline", "tag": "v1.6.0", "attempt": 1}]) + self.assertTrue(historical.calls) + self.assertEqual(old_row, old_before) + self.assertEqual( + {name: raw for (tag, name), raw in store.assets.items() if tag == old_row["tag_name"]}, + old_assets) + self.assertEqual([op for op in store.operations if op[0] == "publish"], + [("publish", "v1.6.0", True)]) + self.assertEqual({op[0] for op in registry.operations}, { + "1.6.0", "engine1.6.0-codegen1.6.0", "sha-" + current["hub_commit"][:7], "latest", "1.6", + }) + incidents = [call.args[2] for call in reports if call.args[1] == old_row["tag_name"]] + self.assertEqual(incidents, [] if ready else ["Release v1.5.9: readiness failed"]) + + def test_freshness_report_does_not_require_the_latest_facts_proof(self): + for state in ("pending", "unprovable"): + with self.subTest(state=state): + manifest = fixture_manifest() + store, registry = MemoryStore(manifest), MemoryRegistry() + row = store.rows["v1.6.0"] + store.put(row, contract.ASSET, contract.canonical(manifest)) + store.operations.clear() + client = FinalizerProofClient(manifest) + client.latest_facts_commit = OTHER + latest = GitHubProof(OTHER, run_offset=3000) + client.proofs.sources[OTHER] = latest + if state == "pending": + latest.runs["facts-validate.yml"][0].update(status="in_progress", conclusion=None) + else: + latest.error = contract.Invalid("proof unavailable") + + result, deliveries, reports = self.sweep(client, store, registry, consumers=("offline", "web")) + self.assertEqual(result, 0) + self.assertEqual(deliveries, [ + {"consumer": role, "tag": "v1.6.0", "attempt": 1} for role in ("offline", "web") + ]) + self.assertIn((HUB, OTHER, "facts/facts.json"), client.file_reads) + self.assertEqual(latest.calls, []) + self.assertTrue(client.proofs.sources[manifest["facts"]["commit"]].calls) + self.assertTrue(any(call.args[1].startswith("facts-") for call in reports)) + self.assertFalse(row["draft"]) + self.assertIsNotNone(store.read(row, "release-ready.json")) + + def test_pending_proof_reports_readiness_pending_without_failing_the_sweep(self): + for target in ("release", "facts"): + for state in ("missing", "running"): + with self.subTest(target=target, state=state): + manifest = fixture_manifest() + store, registry = MemoryStore(manifest), MemoryRegistry() + row = store.rows["v1.6.0"] + if target == "facts": + store.put(row, contract.ASSET, contract.canonical(manifest)) + store.operations.clear() + client = FinalizerProofClient(manifest) + source = client.proofs.sources[manifest["hub_commit"] if target == "release" else manifest["facts"]["commit"]] + if state == "missing": + source.runs["facts-validate.yml"] = [] + else: + source.runs["facts-validate.yml"][0].update(status="in_progress", conclusion=None) + + result, deliveries, reports = self.sweep(client, store, registry) + self.assertEqual(result, 0) + self.assertEqual(deliveries, []) + self.assertEqual([call.args[2] for call in reports], ["Release v1.6.0: readiness pending"]) + self.assertTrue(source.calls) + self.assertEqual(store.operations, []) + self.assertEqual(registry.operations, []) + self.assertTrue(row["draft"]) + self.assertIsNone(store.read(row, "release-ready.json")) + class ProofWorkflowTests(unittest.TestCase): def workflow(self, filename): @@ -483,6 +671,14 @@ def test_reconciliation_requires_exact_checked_out_main_proof(self): self.assertIn('commit --sha "$(git rev-parse HEAD)"', gate["run"]) self.assertLess(steps.index(gate), next(i for i, step in enumerate(steps) if step.get("id") == "app")) + def test_facts_push_waits_for_proof_for_both_consumers(self): + for role in ("web", "license"): + with self.subTest(role=role): + steps = self.workflow("facts-fanout.yml")["jobs"][role]["steps"] + gate = next(step for step in steps if step.get("id") == "main-proof") + self.assertEqual(gate["env"]["WAIT_SECONDS"], "${{ github.event_name == 'push' && '1800' || '0' }}") + self.assertIn('--wait-seconds "$WAIT_SECONDS"', gate["run"]) + if __name__ == "__main__": unittest.main()