fix: recover exact Release Please runs

Author: tensornull

.github/workflows/publish.yml

@@ -157,10 +157,18 @@ jobs:
           RELEASE_JSON="$release_json" TAG_COMMIT="$tag_commit" \
             node --input-type=module <<'EOF'
           import { readFileSync } from "node:fs";
-          import { validateGitHubRelease } from "./scripts/release-workflow-validation.mjs";
+          import {
+            extractReleaseNotesFromChangelog,
+            validateGitHubRelease,
+          } from "./scripts/release-workflow-validation.mjs";
 
           const release = JSON.parse(readFileSync(process.env.RELEASE_JSON, "utf8"));
+          const version = JSON.parse(readFileSync("package.json", "utf8")).version;
           validateGitHubRelease(release, {
+            expectedBody: extractReleaseNotesFromChangelog(
+              readFileSync("CHANGELOG.md", "utf8"),
+              version,
+            ),
             htmlUrl: process.env.RELEASE_HTML_URL,
             releaseCommit: process.env.RELEASE_COMMIT,
             tag: process.env.RELEASE_TAG,

.github/workflows/release-please.yml

@@ -116,39 +116,53 @@ For normal stable patches, Release Please owns the reviewed version/changelog
 PR and the immutable tag and GitHub Release. The configuration uses an explicit
 `cometapi` component and `always-bump-patch` versioning so the authorized 0.1
 maintenance window cannot enter 0.2 implicitly and a root package does not fall
-into the single-package tag-discovery ambiguity encountered during 0.1.0.
+into the single-package tag-discovery ambiguity encountered during 0.1.0. The
+workflow also rejects commit-level `Release-As:` notes before mutation because
+Release Please applies those overrides before its patch versioning strategy.
 Because a
 GitHub Release created with the default `GITHUB_TOKEN` does not start a separate
 `release.published` workflow, publication is chained from the successful
 Release Please workflow. The handoff accepts only the canonical repository's
-successful first-attempt `push` run for `main` at the still-current exact `main`
-SHA. The release workflow records `release_created`, SHA, tag, version, URL,
-repository, workflow identity, run ID, and attempt in an exact-run artifact.
-Publication downloads and validates that artifact before checking the tag and
+successful attempt-qualified `push` run for `main` at the still-current exact
+`main` SHA. The release workflow records normalized action outcome, recovery
+state, pre-action Release presence, the exact Release-producing attempt, SHA,
+tag, version, URL, repository, workflow identity, run ID, and attempt in a
+schema-v2 exact-run artifact. Publication
+downloads and validates only that attempt's artifact before checking the tag and
 immutable Release. A first-attempt manual run is explicitly release-inert and
-must succeed only after validating one action-created patch PR; its event cannot
-enter publication. Any successful `push` run without the exact Release
-Please-created result, tag, and immutable Release fails before live or registry
-access. The release outcome and package artifact are verified independently.
+must succeed only after independently validating one canonical action-created
+patch PR; its event cannot enter publication. Any successful `push` run without
+the exact result artifact, tag, and immutable Release fails before live or
+registry access. The release outcome and package artifact are verified
+independently.
 
 Release Please and publication remain separate trust domains. Release Please
 does not receive npm OIDC permission; `id-token: write` remains limited to the
 protected publish job. Repository variables gate both flows, and reruns remain
 fail-closed on exact tag, artifact, dist-tag, integrity, and provenance state.
-Release Please itself rejects attempt 2 or later before repository mutation;
-the explicitly enabled preparation path uses a new manual dispatch with Release
-creation disabled, while only a new `push` run can create the Release and enter
-publication. The authorized Actions setting lets the default token create the
-PR, but bot review cannot satisfy the gate. A merged release PR is accepted for
-tagging only after a distinct repository administrator approved its final head.
-The workflow checks the triggering SHA against the fetched `main` tip both at
-checkout and immediately before Release Please mutation, so an older queued run
-cannot release a newer default-branch commit.
-It also rejects any pending merged release PR whose merge commit is not the
-current push SHA, and scans the complete pending merged set so a legacy, fork,
-alternate, older, or additional PR cannot be tagged. Manual dispatch is
-therefore release-inert: it may prepare one canonical action-created PR only
-when no merged release PR is awaiting a tag.
+Manual preparation rejects attempt 2 or later; restart uses a new dispatch with
+Release creation disabled. A `push` rerun is bounded to the same run ID, SHA,
+candidate, and final-head review. It may retry while the tag and Release remain
+absent. If an earlier attempt already created the Release, recovery accepts only
+the exact bot-authored immutable Release at that SHA whose publication time
+falls inside exactly one earlier Release Please step from the same run.
+Release-mode action failure is tolerated only long enough to
+prove that postcondition, reconcile the release PR to `autorelease: tagged`, and
+write the attempt-qualified artifact. The authorized Actions setting lets the
+default token create the PR; the resulting approval-required CI still needs a
+human with write access to authorize execution, and bot review cannot satisfy
+the release gate. A merged
+release PR is accepted for tagging only after a distinct repository
+administrator approved its final head. The workflow checks the triggering SHA,
+release-branch snapshot, all open and closed PR identities, current review, and
+tag/Release state immediately before Release Please mutation, then rechecks
+`main`, the release branch, the complete PR snapshot, exact final-head approval,
+and the Release body against `CHANGELOG` before accepting the result. It rejects any
+pending merged release PR whose merge commit is not the current push SHA and
+scans the complete pending merged set so a legacy, fork, alternate, older, or
+additional PR cannot be tagged. Manual dispatch is therefore release-inert: it
+may prepare one canonical action-created PR only when no merged release PR is
+awaiting a tag.
 
 ## Testing layers
 

ARCHITECTURE.md

@@ -234,22 +234,26 @@ The repository maintains four independently auditable workflows:
   `LIVE_SMOKE_ENABLED=true`.
 - `release-please.yml`: patch-only versioning, an explicit `cometapi` component,
   separate pull requests, and an explicit component/version title. It requires
-  `RELEASE_PLEASE_ENABLED=true`, accepts only first-attempt runs, and uses the
-  default `GITHUB_TOKEN`. The authorized repository baseline keeps default
-  workflow permissions read-only and allows Actions to create pull requests; it
-  does not make bot review valid release approval. A first-attempt manual
-  dispatch runs with GitHub
-  Release creation disabled and prepares exactly one action-authored patch PR
-  after the variable is enabled; rerunning an older workflow is rejected before
-  Release Please can mutate repository state. The preparation run succeeds only
-  after verifying the canonical branch, title, machine-readable body, pending
-  label, four expected release files, and 0.1.x patch versions. Before a
-  post-merge `push` may create a Release, the workflow scans every merged `main`
-  PR carrying `autorelease: pending`, rejects legacy, alternate, fork, older, or
-  multiple candidates, and requires an administrator's human approval on the
-  exact final head. Release Please then creates the normal tag and GitHub
-  Release, transitions the release label, and uploads its exact release outputs
-  as a run-bound artifact.
+  `RELEASE_PLEASE_ENABLED=true` and uses the default `GITHUB_TOKEN`. The
+  authorized repository baseline keeps default workflow permissions read-only
+  and allows Actions to create pull requests; it does not make bot review valid
+  release approval. A manual dispatch is attempt-1-only, runs with GitHub Release
+  creation disabled, and prepares exactly one action-authored patch PR after the
+  variable is enabled. A new dispatch may revalidate an unchanged canonical PR
+  even when Release Please returns no PR output. The preparation run succeeds
+  only after independently verifying the canonical branch, title,
+  machine-readable body, pending label, four expected release files, and 0.1.x
+  patch versions. Before a post-merge `push` may create a Release, the workflow
+  scans every merged `main` PR carrying `autorelease: pending`, rejects legacy,
+  alternate, fork, older, or multiple candidates, and requires an
+  administrator's human approval on the exact final head. A same-run push retry
+  may proceed only for the same run ID, SHA, candidate, and review. An existing
+  tag and Release are accepted only as the exact bot-authored immutable Release
+  whose publication time falls within exactly one executed Release Please step
+  from an earlier attempt of that run. Release Please then creates or recovers
+  the normal tag and GitHub Release, verifies its notes byte-for-byte against the
+  normalized `CHANGELOG` entry, reconciles the release label, and uploads a
+  schema-v2 attempt-qualified result artifact.
   The triggering SHA must still equal the fetched `main` tip at checkout and
   immediately before the Release Please action; an older queued run stops before
   mutation.
@@ -262,11 +266,13 @@ The repository maintains four independently auditable workflows:
   Please workflow for `main`. This indirection is required because a GitHub
   Release created with the default `GITHUB_TOKEN` does not trigger a new
   `release.published` workflow. The handoff accepts only the canonical
-  repository's successful, first-attempt `push` run for the still-current exact
-  `main` SHA. It downloads the output artifact from that exact upstream run and
-  requires `release_created`, SHA, tag, version, URL, repository, workflow path,
-  run ID, and attempt to agree before accepting the matching Release
-  Please-created version tag and immutable GitHub Release. A successful manual
+  repository's successful attempt-qualified `push` run for the still-current
+  exact `main` SHA. It downloads the output artifact from that exact upstream
+  run ID and attempt and requires schema version, normalized action outcome,
+  recovery state, pre-action Release presence, exact Release-producing attempt,
+  SHA, tag, version, URL, repository, workflow path, run ID, and attempt to agree
+  before accepting the
+  matching version tag and immutable GitHub Release. A successful manual
   preparation run is release-inert and cannot enter publication; a successful
   `push` run without the exact release result fails before live or publication
   work. The release path then packs and tests one exact, attempt-qualified
@@ -470,24 +476,46 @@ The release workflow must never change either setting, and any later drift is a
 stop condition.
 
 After enabling `RELEASE_PLEASE_ENABLED`, start a new manual dispatch on `main`;
-do not rerun the skipped workflow from the repair merge. Only attempt 1 may call
-Release Please. The workflow rejects any dispatch whose triggering ref is not
-`refs/heads/main`, and all preparation and release runs share one main-scoped
-concurrency group. The manually dispatched preparation run cannot trigger npm
-publication or create a Release: the action receives explicit
+do not rerun the skipped workflow from the repair merge. Only attempt 1 of a
+manual dispatch may call Release Please; an unchanged PR is restarted with a
+new dispatch, not a rerun. The workflow rejects any dispatch whose triggering
+ref is not `refs/heads/main`, and all preparation and release runs share one
+main-scoped concurrency group. The manually dispatched preparation run cannot
+trigger npm publication or create a Release: the action receives explicit
 `skip-github-release=true`, it is accepted only when no merged
 `autorelease: pending` PR exists, and `publish.yml` accepts only an upstream
-`push` event. It must succeed after validating the one action-created 0.1.1 PR.
-Before mutation, the workflow also rejects any open PR whose head name could be
-mistaken for the canonical release branch, including a same-named fork branch.
+`push` event. It must succeed after independently validating the one canonical
+action-created 0.1.1 PR, including the unchanged-PR case where the action emits
+no `prs` output. Before mutation, the workflow also rejects any open PR whose
+head name could be mistaken for the canonical release branch, including a
+same-named fork branch.
+The `GITHUB_TOKEN`-created PR's `pull_request` CI starts in GitHub's
+approval-required state. A human with write access must explicitly authorize
+those workflow runs before their results can satisfy required checks; this is
+separate from the final-head administrator review.
 Remove the one-cycle `last-release-sha` from that branch, complete the
 release-ready documentation, run the full matrix on its final head, and obtain
 approval from a different human repository administrator. The release-PR merge
-creates the new first-attempt `push` run that may tag and publish. A later push
-cannot tag an older outstanding release PR; its merge SHA must equal the
-triggering SHA before Release Please runs. Immediately before the irreversible
-Release Please call, the push run also requires final release metadata and
-public documentation, including removal of the one-cycle `last-release-sha`.
+creates the `push` run that may tag and publish. A later push cannot tag an older
+outstanding release PR; its merge SHA must equal the triggering SHA before
+Release Please runs. A rerun may retry that same candidate while no tag or
+Release exists. If Release Please created the immutable Release but failed
+before producing outputs, only the same run may recover it, and only after
+proving its exact SHA, tag, bot author, immutable state, target, URL, notes, and
+publication inside exactly one earlier Release Please step time window. Recovery
+then idempotently removes `autorelease: pending`,
+adds `autorelease: tagged`, and writes a schema-v2 artifact for that attempt.
+Immediately before the irreversible Release Please call, every attempt also
+reconfirms `main`, the release-branch snapshot, all PR collisions, the candidate
+and final-head review, final release metadata and public documentation, and the
+exact tag/Release state, including removal of the one-cycle `last-release-sha`.
+Because workflow concurrency does not lock `main` or PR metadata against other
+actors, the maintainer must hold a short mutation freeze from the release-PR
+merge until the Release Please run reaches its post-action validation. Do not
+merge another `main` PR, edit the release PR, change its labels or review, or
+mutate the release branch during that window. The workflow repeats those checks
+after the action and stops publication on any drift, but it cannot delete or
+replace an immutable Release created during an external race.
 
 The stale branch
 `release-please--branches--main--components--cometapi` at
@@ -546,6 +574,17 @@ PRs, and normal Release Please tag and GitHub Release creation. Repository
 Actions pull-request authorization is now enabled for that scoped job; the
 workflow still uses only its default token and job-local permissions.
 
+The recovery rules follow the pinned implementation rather than assuming the
+action is atomic. Release Please 17.6.0
+[creates the Release before PR comments and label changes](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/manifest.ts#L1258-L1319),
+while the pinned action emits release outputs only after that call returns. An
+unchanged release PR may also return
+[no PR result](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/manifest.ts#L1089-L1101).
+Finally, commit-level `Release-As:` is rejected before the action because the
+[base strategy applies it before configured versioning](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/strategies/base.ts#L543-L570).
+GitHub documents that a `GITHUB_TOKEN`-created PR's opened or synchronize event
+[creates an approval-required workflow run](https://github.com/github/docs/blob/e1e4aa937308f21c411c248b4966873536bb0cba/data/reusables/actions/actions-do-not-trigger-workflows.md#L1-L6).
+
 ## Stable 0.1.0 release evidence
 
 Stable `0.1.0` completed on 2026-07-28 with these independently auditable

RELEASING.md

@@ -116,11 +116,13 @@ repository setting. Patch-only versioning prevents an implicit 0.2 bump during
 this maintenance window. The temporary anchor must be removed in that release
 PR before merge. The explicit component does not enter the public tag; the only
 accepted patch tag is `v0.1.1`. Publication is triggered from the successful
-first-attempt Release Please push run and independently verifies that run's
-exact release-created output artifact, default-branch commit, tag, immutable
-Release, and package artifact before the existing bounded live smoke and npm
-OIDC steps. The post-merge run also requires an administrator's approval on the
-release PR's final head.
+attempt-qualified Release Please push run and independently verifies that run's
+schema-v2 result artifact, default-branch commit, tag, immutable Release, and
+package artifact before the existing bounded live smoke and npm OIDC steps. A
+push rerun is bounded to the same run ID, SHA, candidate, Release-producing
+attempt, and exact Release state; manual preparation remains attempt-1-only.
+The Release notes must equal the reviewed `CHANGELOG` entry. The post-merge run also
+requires an administrator's approval on the release PR's final head.
 
 The exact stale branch remains failure evidence until its contents, lack of an
 open PR, and lack of independent work are reconfirmed immediately before
@@ -282,8 +284,9 @@ component identity, patch versioning, pull-request configuration, one-cycle
 creation, and a trusted `workflow_run` handoff to the existing exact-artifact,
 bounded-live, and npm OIDC gates. Regression tests must reject stale manifest
 state, a 0.2 bump, missing PR configuration, an unrelated stale branch, hostile
-workflow events, reruns, mismatched action outputs, missing final-head approval,
-and declaration or runtime option bypasses.
+workflow events, unsafe or mismatched recovery attempts, mismatched action
+outputs, missing final-head approval, and declaration or runtime option
+bypasses.
 
 Exit criteria:
 
@@ -405,10 +408,13 @@ merge. Because the default `GITHUB_TOKEN` cannot cause a second workflow through
 a `release.published` event, `publish.yml` starts from successful Release Please
 workflow completion and re-establishes trust from exact repository state.
 Failed pull-request preparation runs are filtered out; any successful run
-without a run-bound `release_created` result, the exact Release Please-created
-tag, and immutable Release fails before live or registry access. Only a
-successful canonical first-attempt `push` run for the still-current exact
-`main` SHA can enter artifact verification.
+without a schema-v2 attempt-bound release result, the exact tag, and immutable
+Release fails before live or registry access. Only a successful canonical
+attempt-qualified `push` run for the still-current exact `main` SHA can enter
+artifact verification. A push retry may recover only the same run ID, SHA,
+candidate, and exact bot-authored immutable Release published inside one
+earlier Release Please step; manual preparation
+reruns remain forbidden.
 
 Public Preview needs no registry workflow. Registry Alpha publishes from a
 human-reviewed immutable prerelease tag under the `next` dist-tag through OIDC