Release automation: docs tuple lag must not reverse package publication success (#255)

Author: durable-workflow-ops

.github/workflows/publish.yml

@@ -158,6 +158,7 @@ jobs:
           DOCS_RELEASE_AUDIT_VERSION: ${{ needs.build.outputs.release_tag }}
           DOCS_RELEASE_AUDIT_EVIDENCE: docs-release-audit-evidence.json
           DOCS_RELEASE_AUDIT_HANDOFF: docs-release-audit-handoff.json
+          DOCS_RELEASE_AUDIT_ENFORCEMENT: advisory
         run: scripts/ci/check-docs-release-audit.sh
 
       - name: Upload docs release audit evidence

scripts/ci/check-docs-release-audit.sh

@@ -25,6 +25,26 @@ attempts="${DOCS_RELEASE_AUDIT_ATTEMPTS:-6}"
 sleep_seconds="${DOCS_RELEASE_AUDIT_RETRY_SLEEP:-20}"
 evidence_path="${DOCS_RELEASE_AUDIT_EVIDENCE:-}"
 handoff_path="${DOCS_RELEASE_AUDIT_HANDOFF:-}"
+enforcement="${DOCS_RELEASE_AUDIT_ENFORCEMENT:-required}"
+
+report_docs_freshness() {
+    title="$1"
+    message="$2"
+
+    if [ "$enforcement" = "required" ]; then
+        fail "$title" "$message"
+    fi
+
+    if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+        {
+            printf '## %s\n\n' "$title"
+            printf '%s\n' "$message"
+        } >> "$GITHUB_STEP_SUMMARY"
+    fi
+
+    printf '::warning title=%s::%s\n' "$title" "$message" >&2
+    printf '%s\n' "$message" >&2
+}
 
 write_unavailable_evidence() {
     message="$1"
@@ -35,6 +55,8 @@ write_unavailable_evidence() {
 const fs = require('fs');
 
 const [evidencePath, artifact, expected, auditUrl, message] = process.argv.slice(2);
+const repository = process.env.GITHUB_REPOSITORY || null;
+const runId = process.env.GITHUB_RUN_ID || null;
 
 fs.writeFileSync(evidencePath, `${JSON.stringify({
   schema: 'durable-workflow.release.docs-release-audit-evidence',
@@ -44,6 +66,18 @@ fs.writeFileSync(evidencePath, `${JSON.stringify({
   artifact,
   expected_version: expected,
   outcome: 'unavailable',
+  lifecycle: 'docs_freshness',
+  publication_outcome_impact: 'none',
+  source_release_check: {
+    repository,
+    ref: process.env.GITHUB_REF_NAME || null,
+    sha: process.env.GITHUB_SHA || null,
+    run_id: runId,
+    run_attempt: process.env.GITHUB_RUN_ATTEMPT || null,
+    run_url: repository && runId
+      ? `${process.env.GITHUB_SERVER_URL || 'https://github.com'}/${repository}/actions/runs/${runId}`
+      : null,
+  },
   message,
 }, null, 2)}\n`);
 NODE
@@ -59,6 +93,11 @@ if [ -z "$expected" ]; then
     fail "Docs release-audit version required" "DOCS_RELEASE_AUDIT_VERSION or GITHUB_REF_NAME must name the published artifact version."
 fi
 
+case "$enforcement" in
+    required|advisory) ;;
+    *) fail "Invalid docs release-audit enforcement" "DOCS_RELEASE_AUDIT_ENFORCEMENT must be required or advisory." ;;
+esac
+
 case "$attempts" in
     ''|*[!0-9]*) fail "Invalid docs release-audit retry count" "DOCS_RELEASE_AUDIT_ATTEMPTS must be a positive integer." ;;
 esac
@@ -76,10 +115,10 @@ attempt=1
 
 while [ "$attempt" -le "$attempts" ]; do
     if curl -fsSL --retry 3 --retry-all-errors --connect-timeout 10 --max-time 30 -o "$audit_path" "$audit_url"; then
-        if node - "$audit_path" "$artifact" "$expected" "$audit_url" "$evidence_path" "$handoff_path" <<'NODE'
+        if node - "$audit_path" "$artifact" "$expected" "$audit_url" "$evidence_path" "$handoff_path" "$enforcement" <<'NODE'
 const fs = require('fs');
 
-const [auditPath, artifact, expected, auditUrl, evidencePath, handoffPath] = process.argv.slice(2);
+const [auditPath, artifact, expected, auditUrl, evidencePath, handoffPath, enforcement] = process.argv.slice(2);
 const title = 'Docs release-audit tuple stale';
 const refreshCommand = 'npm run refresh:public-artifact-versions';
 const refreshFiles = [
@@ -122,6 +161,8 @@ function docsRefreshHandoff(message, actualVersion, observedVersions) {
     schema: 'durable-workflow.release.docs-artifact-tuple-handoff',
     schema_version: 1,
     action: 'pipeline_ready_item',
+    lifecycle: 'docs_freshness',
+    priority: 'low',
     reason: 'public_docs_release_audit_stale',
     repository: 'durable-workflow.github.io',
     target_branch: 'main',
@@ -158,6 +199,7 @@ function docsRefreshHandoff(message, actualVersion, observedVersions) {
         'pipeline:ready-item',
         'branch:main',
         'state:pending',
+        'priority:P3',
       ],
       acceptance: [
         'The public docs release-audit JSON reports the current published artifact tuple.',
@@ -207,6 +249,8 @@ function writeEvidence(outcome, extra = {}) {
     artifact,
     expected_version: expected,
     source_release_check: releaseCheckSource(),
+    lifecycle: 'docs_freshness',
+    publication_outcome_impact: 'none',
     outcome,
     ...extra,
   }, null, 2)}\n`);
@@ -230,9 +274,10 @@ function fail(message, extra = {}) {
       `## ${title}\n\n${message}\n\n`
     );
   }
-  console.error(`::error title=${title}::${message}`);
+  const annotation = enforcement === 'advisory' ? 'warning' : 'error';
+  console.error(`::${annotation} title=${title}::${message}`);
   console.error(message);
-  process.exit(2);
+  process.exit(enforcement === 'advisory' ? 0 : 2);
 }
 
 let audit;
@@ -294,4 +339,4 @@ done
 
 message="Could not fetch ${audit_url} after ${attempts} attempt(s)."
 write_unavailable_evidence "$message"
-fail "Docs release-audit unavailable" "$message"
+report_docs_freshness "Docs release-audit unavailable" "$message"

scripts/ci/test-component-release-recovery.py

@@ -364,6 +364,98 @@ def test_fresh_dispatch_keeps_partial_publication_idempotent(self) -> None:
         self.assertIn('if ! gh release view "$RELEASE_TAG"', workflow)
 
 
+class PublishedReleaseRecoveryTest(unittest.TestCase):
+    RELEASE_TAG = "0.4.101"
+    RELEASE_COMMIT = "8aa0e86fe51edc1e7aba3d97ddf3dfda8009ee23"
+    PLAN_TAG = "release-plan/alpha-continuity"
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.recovery = load_recovery_module()
+
+    def test_publication_authority_uses_exact_tag_distribution_and_release(self) -> None:
+        client = mock.Mock(spec=self.recovery.PublicClient)
+        identity = {"version": self.RELEASE_TAG, "commit": self.RELEASE_COMMIT}
+        distribution_evidence = {"kind": "pypi", "source_files_compared": 12}
+        release_evidence = {"tag_name": self.RELEASE_TAG}
+        distribution_verifier = mock.Mock(return_value=distribution_evidence)
+
+        with (
+            mock.patch.object(self.recovery, "require_source_tag") as source_tag_verifier,
+            mock.patch.object(
+                self.recovery,
+                "verify_github_release",
+                return_value=release_evidence,
+            ) as release_verifier,
+            mock.patch.dict(self.recovery.VERIFIERS, {"pypi": distribution_verifier}),
+        ):
+            evidence = self.recovery.verify_component(client, "sdk-python", identity)
+
+        source_tag_verifier.assert_called_once_with(client, "sdk-python", identity)
+        distribution_verifier.assert_called_once_with(
+            client,
+            self.recovery.COMPONENTS["sdk-python"],
+            self.RELEASE_TAG,
+            self.RELEASE_COMMIT,
+        )
+        release_verifier.assert_called_once_with(client, "sdk-python", self.RELEASE_TAG)
+        self.assertEqual(evidence["version"], self.RELEASE_TAG)
+        self.assertEqual(evidence["commit"], self.RELEASE_COMMIT)
+        self.assertEqual(evidence["distribution"], distribution_evidence)
+        self.assertEqual(evidence["github_release"], release_evidence)
+
+    def test_exact_public_release_completes_without_publication_dispatch(self) -> None:
+        client = mock.Mock(spec=self.recovery.PublicClient)
+        plan = {
+            "plan": "alpha-continuity",
+            "channel": "alpha",
+            "components": {
+                "server": {"version": "0.2.700", "commit": "2" * 40},
+                "sdk-python": {"version": self.RELEASE_TAG, "commit": self.RELEASE_COMMIT},
+            },
+        }
+        package_evidence = {
+            "version": self.RELEASE_TAG,
+            "commit": self.RELEASE_COMMIT,
+            "distribution": {"kind": "pypi", "source_files_compared": 12},
+            "github_release": {"tag_name": self.RELEASE_TAG},
+        }
+
+        def verify_public_component(
+            _client: object, component: str, _identity: dict[str, str]
+        ) -> dict[str, object]:
+            if component == "sdk-python":
+                return package_evidence
+            return {"version": plan["components"][component]["version"]}
+
+        with (
+            mock.patch.object(self.recovery, "verify_plan_authority", return_value=({}, {})),
+            mock.patch.object(self.recovery, "verify_component", side_effect=verify_public_component),
+            mock.patch.object(self.recovery, "resolve_tag", return_value=self.RELEASE_COMMIT),
+            mock.patch.object(
+                self.recovery,
+                "require_python_source_manifest_version",
+                return_value={"declared_version": self.RELEASE_TAG, "source_commit": self.RELEASE_COMMIT},
+            ),
+        ):
+            state, outputs = self.recovery.resolve_component(
+                client,
+                "sdk-python",
+                self.PLAN_TAG,
+                "3" * 40,
+                plan,
+            )
+
+        self.assertEqual(outputs["action"], "skip")
+        self.assertEqual(state["phase"], "complete")
+        self.assertEqual(state["outcome"], "verified")
+        self.assertEqual(state["public_evidence"], package_evidence)
+
+        workflow = RECOVERY_WORKFLOW.read_text()
+        publication_step = workflow[workflow.index("Start or resume repository-owned publication") :]
+        self.assertIn("if: steps.recovery.outputs.action == 'publish'", publication_step)
+
+
 class PythonSourceManifestPreflightTest(unittest.TestCase):
     RELEASE_TAG = "0.4.100"
     RELEASE_COMMIT = "2018400368cf4251c58b24b3d53a99f0ca3512e3"