docs: make release archives immutable

[jeremi]

Pull Request

Summary

Make archived documentation actual immutable release artifacts instead of rebuilding all historical releases during routine checks and every Pages deployment.

Recent runs spent about 8.5 minutes rebuilding 15 archives, including roughly 75 shallow product-repository clones per sweep. Those outputs were not truly frozen because current templates, dependencies, analytics settings, timezone, and Pagefind could change their bytes.

This change:

• adds an append-only archive-lock.yaml binding every archived docset to its deterministic bundle and extracted-tree SHA-256
• baselines the 15 existing release trees once, without committing the 66 MB of bundle files
• makes normal npm run check current-site-only and runs archive verification only when archive machinery, pins, dependencies, workflows, or the lock change
• preserves changed paths during full push and merge-queue matrices, so unrelated changes do not select archive verification
• makes Pages resolve a locked GitHub Release asset first, then the self-hosted historical fallback, and bootstrap a missing bundle only on the explicit publication path
• builds each future archive once from the exact release tag in an unprivileged job, then includes it in release checksums, file SBOMs, cosign signatures, SLSA provenance, and the release capsule
• disables Pagefind and mutable analytics only in archived builds; current documentation keeps both

This is deliberately different from the closed cache PR #432. There are no mutable cache keys or invalidation policy. The verified bundle is the archive contract.

Checks

• npm ci on Node 22.12.0
• npm audit --audit-level=high (0 vulnerabilities)
• npm test (133 tests passed)
• npm run check (current site, 34,195 internal links/assets)
• npm run check:archives (15 restored, 0 rebuilt; 3,531 archived HTML files; 594,346 internal links/assets)
• full one-time 15-release baseline build
• repeated v0.13.0 build and bundle comparison produced identical tree and bundle digests
• release/scripts/registry-release validate-docsets
• release tooling, release planning, OCI-label, gate-inventory, source-model, CI-classifier, and Debian 13 image test suites
• release/scripts/check-release-source-model.sh in monorepo mode
• actionlint for CI, Pages, and release workflows
• git diff --check

Notes

Migration intentionally changes existing archived output once at cutover: archived local search and deployment analytics are removed so the frozen bytes are platform-independent and configuration-independent. The first Pages deployment publishes the locked historical fallback bundles. Historical GitHub Releases are not modified.

Archive extraction is fail-closed: bundle and tree hashes are verified, paths and entry types are constrained, symlinks are rejected, and compressed/downloaded size, extracted size, and entry counts are bounded. A bad canonical source never falls through to a different source.

Future release preparation builds only the new archive and appends one lock entry. Existing entries cannot be edited or removed.

DCO

• Every commit includes a Signed-off-by trailer.
• I reviewed the submitted changes and am responsible for the contribution.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5857ca37ef

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf01a117cf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ca2921b0a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.