Fix queued docs deployments deleting published releases

[yuecideng]

Description

Prevent an older main documentation artifact from deleting a release that was published while that artifact was waiting to deploy. On October 12, v0.3.1 deployed successfully at 13:23 UTC, then a queued main artifact whose latest version was v0.3.0 replaced the site at 13:24 UTC.

Both deployment paths now merge the current published site inside the Pages concurrency lock, replacing only the version explicitly rebuilt by the candidate. Require the exact deployed Pages artifact to preserve every static resource, including JavaScript-loaded architecture data, and keep those artifacts for 90 days. Abort before changing candidate content when the published artifact is missing or expired; a webpage crawl cannot establish a complete site snapshot. Abort on unavailable manifests or incomplete content, regenerate the version selector and redirect after merging, and retain the newest five releases.

Verify the deployed marker, complete version manifest and every version homepage. Release events dispatch an authoritative child workflow and report its link without timing out while a self-hosted runner is queued. Manual recovery can reuse either a CI docs-site artifact or a docs-site-manual artifact.

Recovery completed with Pages deployment 39010435914, reusing ref=v0.3.1, artifact_run_id=38240255894 and artifact_name=docs-site-manual. The public site now lists v0.3.1 as latest while retaining main and the four older releases. All six version homepages, the root redirect, stylesheet assets and both main/release architecture JSON files return HTTP 200.

The simulator test image now explicitly installs Node.js 22 before workflow contract tests. A full CI run otherwise failed only the six JavaScript cleanup-workflow tests because node was absent (7,364 tests passed).

No package or wheel changes. The 0.3.1 PyPI wheel downloads successfully and its SHA-256 matches PyPI.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Validation

• Full PR CI passed: 7,371 CPU tests, 326 GPU tests and 358 simulator tests passed; no non-slow distributed tests matched. Documentation tests and the full Sphinx build also passed.

• 99 documentation tool tests passed, including delayed main/release deployment, stale cached main, retention, missing content, expired artifacts without mutation, runtime-loaded resource preservation, exact artifact recovery and verification failures.

• 20 workflow contract and merged-PR cleanup tests passed, including all six tests that previously failed because CI lacked Node.

• actionlint 1.7.12 passed for docs-pages.yml and main.yml.

• black 26.3.1: black . completed.

• API documentation coverage: 2602/2602 exports.

• git diff --check passed.

• Real recovery preflight passed using release run 38240255894 and the exact live Pages artifact from run 38999139455: restored latest=v0.3.1 with all six version homepages, and main/index.html matches the current live page byte-for-byte.

• Context impact review: no affected topics; MAP has no release/docs-deployment topic, so no existing guidance needs revision.

Checklist

• I have run the black . command to format the code base.
• I reviewed affected documentation and agent context, updated it where needed, or explained why no update was needed.
• Public API changes are reflected in the API docs (not applicable: deployment tooling only; coverage gate passed).
• I have added tests that prove my fix is effective.
• Dependencies have been updated, if applicable (deployment job explicitly installs packaging; no package dependencies changed).

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge; no actionable new issues remain.

Summary

The PR merges the currently published documentation immediately before deployment, while holding the shared Pages lock.

• Queued documentation deployments keep the versions live when they start.
• Pages jobs prepare and check each site before they finish.
• Simulator CI now has Node.js for workflow tests.

The earlier explorer-data finding is fixed: preparation now requires a complete artifact instead of falling back to a webpage crawl. No new actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Candidate documentation artifact] --> B[Shared Pages lock]
  B --> C[Read live deployment marker]
  C --> D[Download exact published artifact]
  D --> E[Keep rebuilt version and refresh other published versions]
  E --> F[Retain five releases and regenerate selector]
  F --> G[Stamp and upload Pages artifact]
  G --> H[Deploy Pages]
  H --> I[Check marker, manifest, and homepages]
  D -->|Missing or expired| J[Stop without changing candidate]

Loading

_{Reviews (3) · Last reviewed commit: "fix(ci): install Node for workflow contr..." · Reviewed by Greptile}