fix: harden post-publication convergence

Author: tensornull

.github/workflows/publish.yml

@@ -704,6 +704,7 @@ jobs:
           name: ${{ needs.verify.outputs.artifact-name }}
           path: release-artifacts
       - name: Reconfirm protected state immediately before publication
+        id: pre-publish
         env:
           CONTROL_COMMIT: ${{ needs.verify.outputs.control-commit }}
           CONTROL_VALIDATOR: ${{ runner.temp }}/release-workflow-validation.mjs
@@ -890,9 +891,15 @@ jobs:
             version,
           });
           EOF
+          if [[ -n "$exact_version" ]]; then
+            echo "expect-existing=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "expect-existing=false" >> "$GITHUB_OUTPUT"
+          fi
       - name: Publish the exact artifact with provenance
         env:
           DIST_TAG: ${{ needs.verify.outputs.dist-tag }}
+          EXPECT_EXISTING: ${{ steps.pre-publish.outputs.expect-existing }}
           VERSION: ${{ needs.verify.outputs.version }}
         run: bash scripts/publish-artifact.sh
       - name: Verify the public registry artifact
@@ -949,7 +956,37 @@ jobs:
 
           attestations_url="$(REGISTRY_DIST="$registry_dist" node -e 'process.stdout.write(JSON.parse(process.env.REGISTRY_DIST).attestations.url)')"
           attestations_file="$RUNNER_TEMP/npm-attestations.json"
-          curl --fail --silent --show-error "$attestations_url" > "$attestations_file"
+          ATTESTATIONS_FILE="$attestations_file" \
+            ATTESTATIONS_URL="$attestations_url" \
+            bash scripts/fetch-attestations.sh
+
+          post_exact_version="$(npm view "cometapi@${VERSION}" version)"
+          post_tagged_version="$(npm view "cometapi@${DIST_TAG}" version)"
+          post_next_version="$(npm view cometapi@next version)"
+          post_registry_dist="$(npm view "cometapi@${VERSION}" dist --json)"
+          ATTESTATIONS_URL="$attestations_url" \
+            EXACT_VERSION="$post_exact_version" \
+            EXPECTED_INTEGRITY="$local_integrity" \
+            NEXT_VERSION="$post_next_version" \
+            REGISTRY_DIST="$post_registry_dist" \
+            TAGGED_VERSION="$post_tagged_version" \
+            node --input-type=module <<'EOF'
+          import { pathToFileURL } from "node:url";
+
+          const { validatePublishedRegistryState } = await import(
+            pathToFileURL(process.env.CONTROL_VALIDATOR)
+          );
+          validatePublishedRegistryState({
+            attestationUrl: process.env.ATTESTATIONS_URL,
+            dist: JSON.parse(process.env.REGISTRY_DIST),
+            exactVersion: process.env.EXACT_VERSION,
+            expectedIntegrity: process.env.EXPECTED_INTEGRITY,
+            nextVersion: process.env.NEXT_VERSION,
+            taggedVersion: process.env.TAGGED_VERSION,
+            version: process.env.VERSION,
+          });
+          EOF
+          registry_dist="$post_registry_dist"
           local_sha512="$(node -e 'const {createHash}=require("node:crypto");const {readFileSync}=require("node:fs");process.stdout.write(createHash("sha512").update(readFileSync(process.argv[1])).digest("hex"))' "${tarballs[0]}")"
           provenance_identity="$(ATTESTATIONS_FILE="$attestations_file" \
             LOCAL_SHA512="$local_sha512" node --input-type=module <<'EOF'

AGENTS.md

@@ -284,8 +284,19 @@ repository root.
   dispatch. Do not rerun a preparation dispatch. Release Please same-run Release
   reconciliation is allowed only under the exact conditions in `RELEASING.md`.
 - Never bypass a failed stable release with a manual or auxiliary tag, a
-  branch-context publish, a temporary `main` npm Environment policy, reused
-  artifact or live evidence, an arbitrary rerun, or a different patch version.
+  branch-context publish, a temporary `main` npm Environment policy, cross-run
+  artifact or live-evidence reuse, an arbitrary rerun, or a different patch
+  version.
+- If `npm publish` succeeds but post-publication verification fails, first read
+  the exact public version, dist-tags, integrity, attestation URL, signature,
+  and provenance. A transient attestation-endpoint `404` is a registry
+  convergence condition and the workflow must retry it with a finite bound. If
+  exact integrity matches, only `rerun failed jobs` on the same immutable-tag
+  run may resume verification. Confirm that GitHub preserves the successful
+  exact-artifact and live-smoke jobs, so the three-request smoke is not repeated;
+  stop if the replay expands that job set. The replay must remain fail-closed,
+  requires a fresh Environment approval, and must not publish again. Stop on any
+  identity, integrity, provenance, dist-tag, or configuration mismatch.
 - After registry verification, immediately restore
   `RELEASE_PLEASE_ENABLED=false`, keep `LIVE_SMOKE_ENABLED=true`, and require the
   npm Environment deployment-policy set to contain only `tag:v*`.

ARCHITECTURE.md

@@ -153,6 +153,16 @@ 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.
+Registry package metadata and its attestation endpoint can converge at
+different times. Post-publication verification therefore retries attestation
+HTTP failures within a fixed time bound before failing, while preserving exact
+integrity and provenance validation. If publication succeeded before a later
+gate failed, only an idempotent replay of that same immutable-tag run may
+continue. The protected-state step records whether the exact version already
+exists; `publish-artifact.sh` then skips registry mutation only after its
+integrity matches the verified tarball and refuses a later `E404` instead of
+republishing. A failed-job replay preserves the same run's successful artifact
+and bounded live-smoke jobs rather than borrowing evidence from another run.
 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

RELEASING.md

@@ -345,7 +345,9 @@ The repository maintains four independently auditable workflows:
   stable `v0.1.x` tag and release commit. Replays are integrity-idempotent, not
   exactly-once: an existing version is accepted only when its registry integrity
   matches the downloaded artifact, after which the bounded registry, signature,
-  and provenance checks run again.
+  and provenance checks run again. Package metadata and the attestation endpoint
+  may converge independently, so attestation HTTP failures, including an early
+  `404`, receive a bounded ten-minute retry. Exhaustion remains a hard failure.
 
 The one-time `0.1.1` main-context publication exception is historical evidence,
 not a reusable release route. Its dispatch inputs, fixed evidence identifiers,
@@ -560,13 +562,14 @@ or any head change, invalidates the approval.
 The release-PR merge creates the only `push` run that may call Release Please in
 release mode. From that merge through successful registry verification and the
 final readback, do not start a new Release Please workflow or rerun any run
-except the bounded source-run retry described below; publication freezes the
-complete Release Please run set. Through post-action validation, do not edit the
-release PR, change its labels or review, or mutate its branch. Keep `main` frozen
-at the release commit through successful registry verification and the final
-variable and Environment-policy readback; every handoff, tag, and pre-publish
-gate requires that exact identity. A rerun may retry the same release candidate
-only while no tag or Release exists. If an earlier attempt of that same run
+except the bounded source-run retry described below or the exact post-publish
+failed-job replay described after the handoff; publication freezes the complete
+Release Please run set. Through post-action validation, do not edit the release
+PR, change its labels or review, or mutate its branch. Keep `main` frozen at the
+release commit through successful registry verification and the final variable
+and Environment-policy readback; every handoff, tag, and pre-publish gate
+requires that exact identity. A Release Please rerun may retry the same release
+candidate only while no tag or Release exists. If an earlier attempt of that run
 already created the Release, same-run reconciliation is allowed only after
 proving the exact run ID, SHA, tag, bot author, immutable state, target, URL,
 notes, and publication time inside one earlier Release Please step. It may only
@@ -586,6 +589,19 @@ or live evidence, arbitrary rerun, or different patch version. An ambiguous npm
 result requires exact registry integrity, signature, and provenance inspection;
 it never authorizes an automatic retry.
 
+If the exact publish step succeeded but a later registry verification step
+failed, query the immutable version and both dist-tags before taking any action.
+When the public integrity matches the verified artifact and the tag, Release,
+workflow, provenance, and protected configuration remain exact, rerun only the
+failed jobs of that same tag-bound run. Confirm before approval that GitHub kept
+the successful exact-artifact and live-smoke jobs instead of scheduling them
+again; never use rerun-all for this recovery. The protected preflight must record
+that the exact version exists, and the idempotent publication script must report
+matching integrity and skip `npm publish`. A later `E404` is a hard stop rather
+than permission to republish. The failed publish job still requires a fresh npm
+Environment approval. Stop instead of replaying on any mismatch. After
+successful verification, restore `RELEASE_PLEASE_ENABLED=false` immediately.
+
 The `0.1.1` repair used the immutable `0.1.0` commit as a one-cycle
 `last-release-sha` only for its initial preparation, then removed the anchor.
 The failed run's exact generated `0.2.0` branch was verified as failure-only

scripts/fetch-attestations.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+: "${ATTESTATIONS_FILE:?ATTESTATIONS_FILE is required}"
+: "${ATTESTATIONS_URL:?ATTESTATIONS_URL is required}"
+
+connect_timeout="${ATTESTATION_CONNECT_TIMEOUT_SECONDS:-10}"
+max_time="${ATTESTATION_MAX_TIME_SECONDS:-30}"
+retry_count="${ATTESTATION_RETRY_COUNT:-59}"
+retry_delay="${ATTESTATION_RETRY_DELAY_SECONDS:-10}"
+retry_max_time="${ATTESTATION_RETRY_MAX_TIME_SECONDS:-600}"
+
+for value in \
+  "$connect_timeout" \
+  "$max_time" \
+  "$retry_count" \
+  "$retry_delay" \
+  "$retry_max_time"
+do
+  if ! [[ "$value" =~ ^[0-9]+$ ]]; then
+    echo "Attestation retry settings must be non-negative integers." >&2
+    exit 1
+  fi
+done
+
+candidate="${ATTESTATIONS_FILE}.download"
+if ! curl --fail --silent --show-error \
+  --connect-timeout "$connect_timeout" \
+  --max-time "$max_time" \
+  --retry "$retry_count" \
+  --retry-all-errors \
+  --retry-delay "$retry_delay" \
+  --retry-max-time "$retry_max_time" \
+  --remove-on-error \
+  --output "$candidate" \
+  "$ATTESTATIONS_URL"
+then
+  echo "Registry attestations did not converge." >&2
+  exit 1
+fi
+
+mv "$candidate" "$ATTESTATIONS_FILE"

scripts/publish-artifact.sh

@@ -3,8 +3,14 @@
 set -euo pipefail
 
 : "${DIST_TAG:?DIST_TAG is required}"
+: "${EXPECT_EXISTING:?EXPECT_EXISTING is required}"
 : "${VERSION:?VERSION is required}"
 
+if [[ "$EXPECT_EXISTING" != "true" && "$EXPECT_EXISTING" != "false" ]]; then
+  echo "EXPECT_EXISTING must be true or false." >&2
+  exit 1
+fi
+
 artifact_directory="${ARTIFACT_DIRECTORY:-release-artifacts}"
 
 if [[ -n "${NPM_TOKEN:-}" ]] || [[ -n "${NODE_AUTH_TOKEN:-}" ]]; then
@@ -37,6 +43,9 @@ if (dist.integrity !== process.env.LOCAL_INTEGRITY) {
 }
 EOF
   echo "cometapi@${VERSION} already matches the verified artifact; resuming checks."
+elif grep -q "E404" "$view_error" && [[ "$EXPECT_EXISTING" == "true" ]]; then
+  echo "The pre-publish check found this version, but the registry now returns E404; refusing to publish again." >&2
+  exit 1
 elif grep -q "E404" "$view_error"; then
   npm publish "${tarballs[0]}" --access public --provenance --tag "$DIST_TAG"
 else

scripts/release-workflow-validation.mjs

@@ -16,7 +16,7 @@ const RELEASE_WORKFLOW_STEP = "Run Release Please";
 const PUBLISH_OPERATION = "release";
 const NPM_TAG_POLICY_ID = 55718965;
 const PUBLISH_WORKFLOW_CONTRACT_SHA256 =
-  "43f70219c4b8deed5a68a7a369821cc18f891119b373134fda8ca46fc7080e24";
+  "088366a4c0fdb060b330249f4f8db72c97b10925f7f737e47886dffce4dee9be";
 const PUBLISH_HANDOFF_IF =
   "vars.RELEASE_PLEASE_ENABLED == 'true' && github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' && github.event.workflow_run.head_branch == 'main'";
 const PUBLISH_RESULT_IF = "steps.result.outputs.has-result == 'true'";
@@ -504,6 +504,11 @@ export function validatePublishWorkflowContract(workflow) {
     "Reconfirm protected state immediately before publication",
     "Publish protected-state reconfirmation",
   );
+  requireEqual(
+    reconfirmStep?.id,
+    "pre-publish",
+    "Publish protected-state output identity",
+  );
   requireEqual(
     reconfirmStep?.env?.RELEASE_PLEASE_SNAPSHOT,
     "${{ needs.verify.outputs.release-please-snapshot }}",
@@ -546,6 +551,23 @@ export function validatePublishWorkflowContract(workflow) {
     "${{ github.token }}",
     "Publish registry verification token",
   );
+  for (const fragment of [
+    "bash scripts/fetch-attestations.sh",
+    'post_exact_version="$(npm view',
+    'post_tagged_version="$(npm view',
+    'post_next_version="$(npm view cometapi@next version)"',
+    'post_registry_dist="$(npm view',
+    "validatePublishedRegistryState",
+  ]) {
+    if (
+      typeof registryStep?.run !== "string" ||
+      !registryStep.run.includes(fragment)
+    ) {
+      fail(
+        `Release workflow public-registry verification must contain ${fragment}.`,
+      );
+    }
+  }
   const publishSteps = jobs.publish?.steps ?? [];
   if (
     publishSteps.indexOf(reconfirmStep) >= publishSteps.indexOf(publishStep) ||
@@ -560,6 +582,11 @@ export function validatePublishWorkflowContract(workflow) {
     "bash scripts/publish-artifact.sh",
     "npm publication command",
   );
+  requireEqual(
+    publishStep?.env?.EXPECT_EXISTING,
+    "${{ steps.pre-publish.outputs.expect-existing }}",
+    "npm publication replay expectation",
+  );
   requireEqual(
     createHash("sha256").update(JSON.stringify(workflow)).digest("hex"),
     PUBLISH_WORKFLOW_CONTRACT_SHA256,
@@ -865,6 +892,62 @@ export function validateRegistryStateBeforePublish({
   return { exactVersion, latestVersion, nextVersion, previousVersion, version };
 }
 
+export function validatePublishedRegistryState({
+  attestationUrl,
+  dist,
+  exactVersion,
+  expectedIntegrity,
+  nextVersion,
+  taggedVersion,
+  version,
+}) {
+  validateRegistryStateBeforePublish({
+    exactVersion,
+    latestVersion: taggedVersion,
+    nextVersion,
+    version,
+  });
+  requireEqual(exactVersion, version, "published registry exact version");
+  requireEqual(taggedVersion, version, "published registry dist-tag");
+  requireEqual(
+    attestationUrl,
+    `https://registry.npmjs.org/-/npm/v1/attestations/cometapi@${version}`,
+    "published registry attestation URL identity",
+  );
+  if (dist === null || typeof dist !== "object" || Array.isArray(dist)) {
+    fail("Release workflow published registry dist must be an object.");
+  }
+  if (
+    typeof expectedIntegrity !== "string" ||
+    !expectedIntegrity.startsWith("sha512-")
+  ) {
+    fail("Release workflow expected registry integrity must use sha512.");
+  }
+  requireEqual(
+    dist.integrity,
+    expectedIntegrity,
+    "published registry integrity",
+  );
+  requireEqual(
+    dist.attestations?.url,
+    attestationUrl,
+    "published registry attestation URL",
+  );
+  requireEqual(
+    dist.attestations?.provenance?.predicateType,
+    "https://slsa.dev/provenance/v1",
+    "published registry provenance predicate",
+  );
+  return {
+    attestationUrl,
+    exactVersion,
+    integrity: dist.integrity,
+    nextVersion,
+    taggedVersion,
+    version,
+  };
+}
+
 export function validateRegistryProvenance({
   attestations,
   commit,