feat: publish immutable release manifests

Author: speak-agent

.agents/docs/2026-08-09-mcpp-template-runtime-graphics-aur-implementation-plan.md

@@ -274,18 +274,19 @@
 - Add: `scripts/release/generate_manifest.py`
 - Add: `tests/scripts/test_release_manifest.py`
 - Modify: `.github/workflows/release.yml`
-- Modify: `docs/10-distribution.md`
+- Modify: `docs/09-release.md`
+- Modify: `docs/zh/09-release.md`
 
 **Interface:**
 
 - Release asset `mcpp-release.json` schema 1 with version, tag, release commit, and exact name/SHA256 for Linux x86_64/aarch64 plus every shipped platform asset.
 
-- [ ] RED: fixtures reject duplicate platform/arch rows, missing sidecars, mismatched hashes, draft/prerelease input, wrong tag/version, and non-deterministic ordering.
-- [ ] Implement deterministic manifest generation from downloaded release artifacts and sidecars, recomputing every SHA256.
-- [ ] Wire the release workflow so the manifest is uploaded only after all required release assets exist and validation passes.
-- [ ] Add a release gate that downloads the uploaded manifest and compares it to the final GitHub release inventory.
-- [ ] GREEN: run manifest tests and a local fixture generation twice with byte-identical output.
-- [ ] Commit immutable release desired-state manifest.
+- [x] RED: fixtures reject duplicate platform/arch rows, missing sidecars, mismatched hashes, draft/prerelease input, wrong tag/version, and non-deterministic ordering.
+- [x] Implement deterministic manifest generation from downloaded release artifacts and sidecars, recomputing every SHA256.
+- [x] Wire the release workflow so the manifest is uploaded only after all required release assets exist and validation passes.
+- [x] Add a release gate that downloads the uploaded manifest and compares it to the final GitHub release inventory.
+- [x] GREEN: run manifest tests and a local fixture generation twice with byte-identical output.
+- [x] Commit immutable release desired-state manifest.
 
 ## Task 9: Replace Combined AUR Publishing with an mcpp-bin Reconciler
 

.agents/docs/2026-08-09-mcpp-template-runtime-graphics-aur-validation.md

@@ -228,6 +228,24 @@ Task 7 focused local evidence on the latest self-hosted source binary
 - host xlings config aggregate remains `f218aadf3792ee815c8535ce0ca0bb53f634fecbdbc5d0d47db442052d786d1b`.
 - Linux semantics are locally exercised. Mach-O and PE flag spelling has pure unit coverage on Linux; native macOS/Windows compilation and behavior remain latest-HEAD PR CI gates, not inferred passes.
 
+### 5.7 Immutable release desired state (Task 8)
+
+| Gate | RED evidence | Production change | GREEN evidence |
+|---|---|---|---|
+| manifest contract | The initial 11-case suite produced 12 failing assertions because no generator existed; fixtures cover duplicate normalized platform/arch, missing sidecars, payload/sidecar hash disagreement, draft/prerelease releases, wrong tag/version, missing required assets, duplicate release names, and invalid commit identity | Added schema-1 generation from the GitHub release JSON plus downloaded payloads; four current platforms are mandatory, every additional versioned platform payload is included, every digest is recomputed, and output is sorted deterministically | `test_release_manifest.py` passes **12/12**; randomized release-API asset order produces byte-identical output and every manifest hash equals the independently recomputed fixture payload hash |
+| future platform closure | Review fixture added a valid FreeBSD/riscv64 versioned payload; the first implementation stayed green while silently omitting that row | Primary-platform discovery is provider-neutral and version-exact rather than a fixed four-platform allowlist; the four present release targets remain a required floor | The focused future-platform test changed RED-to-GREEN and asserts the complete row and SHA256 occur in the manifest |
+| immutable publication | Previously each platform uploaded independently and downstream jobs inferred completeness from timing and filenames | New `release-manifest` job waits for all four uploaders, validates non-draft/non-prerelease identity, uploads only when absent, refuses a byte-different existing manifest, polls public API visibility, then refetches all public assets and regenerates/compares the manifest | Ruby/Psych parses `release.yml` and confirms six jobs, `publish-ecosystem` depends on `release-manifest`, Python bytecode compilation passes, and `git diff --check` is clean; live GitHub upload/refetch remains a PR/release CI gate |
+| maintainer contract | Release docs had no machine-readable completeness boundary or reproducible local audit command | English and Chinese release docs define schema, row scope, immutability/rerun behavior, public refetch command, and checklist gates | Documentation examples invoke the same checked-in generator and explicitly recompute payload hashes rather than trusting manifest or sidecar values |
+
+Task 8 focused local evidence:
+
+- RED: missing generator yielded 12 assertion failures across 11 initial tests; the later additional-platform review row independently failed because FreeBSD/riscv64 was omitted.
+- GREEN: `python3 tests/scripts/test_release_manifest.py` reports **12 tests OK** in 0.309s; `python3 -m py_compile` succeeds for generator and tests.
+- Determinism: the complete fixture shuffles API inventory with seed 398, invokes the CLI twice to separate output files, and compares exact bytes.
+- Public-inventory replay: downloaded the eight real versioned payload/sidecar assets from stable `v2026.8.8.4`, resolved tag commit `55a39d90fe98b5475fc394ac8487fe6804b2b84f`, and generated twice byte-identically. The four-row manifest SHA256 is `6614ba2db65c8c28cb5a9d3466bd6cf3007634221da76d25216785061c647edb`; every real sidecar and recomputed payload digest agreed.
+- Workflow structure: Ruby/Psych parses `.github/workflows/release.yml`; all six jobs are present and ecosystem publication is gated by the immutable manifest job.
+- Public GitHub upload/refetch and eventual-consistency polling cannot be truthfully claimed from local fixtures; they remain explicit latest-HEAD release CI evidence.
+
 ## 6. Pull request and CI
 
 Not published yet. This section will record PR URL, local/remote HEAD, review state, all latest-head job IDs and terminal conclusions.

.github/workflows/release.yml

@@ -725,16 +725,116 @@ jobs:
             dist/mcpp-windows-x86_64.zip
             dist/mcpp-windows-x86_64.zip.sha256
 
+  # Seal the complete, non-draft release inventory only after every platform
+  # uploader has finished.  The manifest is desired state for downstream
+  # reconcilers: a rerun may reproduce it byte-for-byte, but may never replace
+  # it with different bytes for the same tag.
+  release-manifest:
+    name: validate + seal release manifest
+    needs: [build-release, build-linux-aarch64, build-macos, build-windows]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    timeout-minutes: 20
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve immutable release identity
+        id: resolve
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            TAG="${{ github.ref_name }}"
+          elif [ -n "${{ github.event.inputs.tag }}" ]; then
+            TAG="${{ github.event.inputs.tag }}"
+          else
+            VERSION=$(awk -F '"' '/^version[[:space:]]*=/{print $2; exit}' mcpp.toml)
+            test -n "$VERSION" || { echo 'failed to read [package].version from mcpp.toml'; exit 1; }
+            TAG="v$VERSION"
+          fi
+          git fetch --force origin "refs/tags/$TAG:refs/tags/$TAG"
+          COMMIT=$(git rev-list -n 1 "refs/tags/$TAG")
+          test -n "$COMMIT"
+          echo "tag=$TAG"         >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          echo "commit=$COMMIT"   >> "$GITHUB_OUTPUT"
+
+      - name: Generate, upload once, and refetch manifest
+        run: |
+          TAG="${{ steps.resolve.outputs.tag }}"
+          VERSION="${{ steps.resolve.outputs.version }}"
+          COMMIT="${{ steps.resolve.outputs.commit }}"
+          AUDIT_ROOT=$(mktemp -d)
+          mkdir -p "$AUDIT_ROOT/assets" "$AUDIT_ROOT/publish"
+
+          gh api "repos/${GITHUB_REPOSITORY}/releases/tags/$TAG" \
+            > "$AUDIT_ROOT/release.json"
+          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --dir "$AUDIT_ROOT/assets"
+          python3 scripts/release/generate_manifest.py \
+            --release-json "$AUDIT_ROOT/release.json" \
+            --assets-dir "$AUDIT_ROOT/assets" \
+            --version "$VERSION" \
+            --tag "$TAG" \
+            --commit "$COMMIT" \
+            --output "$AUDIT_ROOT/publish/mcpp-release.json"
+
+          if [ -f "$AUDIT_ROOT/assets/mcpp-release.json" ]; then
+            cmp "$AUDIT_ROOT/assets/mcpp-release.json" \
+                "$AUDIT_ROOT/publish/mcpp-release.json"
+            echo "Existing manifest is byte-identical; leaving it untouched."
+          else
+            gh release upload "$TAG" \
+              "$AUDIT_ROOT/publish/mcpp-release.json" \
+              --repo "$GITHUB_REPOSITORY"
+          fi
+
+          # Do not trust the upload command alone. Fetch the final public
+          # inventory into a clean directory, recompute every payload digest,
+          # regenerate desired state, and compare the published bytes.
+          MANIFEST_VISIBLE=false
+          for attempt in {1..12}; do
+            if gh api "repos/${GITHUB_REPOSITORY}/releases/tags/$TAG" \
+                 --jq '.assets[].name' | grep -Fxq mcpp-release.json; then
+              MANIFEST_VISIBLE=true
+              break
+            fi
+            echo "Waiting for mcpp-release.json API visibility ($attempt/12)"
+            sleep 5
+          done
+          test "$MANIFEST_VISIBLE" = true
+          mkdir -p "$AUDIT_ROOT/final-assets"
+          gh api "repos/${GITHUB_REPOSITORY}/releases/tags/$TAG" \
+            > "$AUDIT_ROOT/final-release.json"
+          gh release download "$TAG" --repo "$GITHUB_REPOSITORY" \
+            --dir "$AUDIT_ROOT/final-assets"
+          test -f "$AUDIT_ROOT/final-assets/mcpp-release.json"
+          python3 scripts/release/generate_manifest.py \
+            --release-json "$AUDIT_ROOT/final-release.json" \
+            --assets-dir "$AUDIT_ROOT/final-assets" \
+            --version "$VERSION" \
+            --tag "$TAG" \
+            --commit "$COMMIT" \
+            --output "$AUDIT_ROOT/final-expected.json"
+          cmp "$AUDIT_ROOT/final-assets/mcpp-release.json" \
+              "$AUDIT_ROOT/final-expected.json"
+          cat "$AUDIT_ROOT/final-assets/mcpp-release.json"
+
   # Publish this release into the xlings ecosystem, after ALL platform builds
-  # have uploaded their assets:
+  # have uploaded their assets and the immutable manifest gate has passed:
   #   ① mirror binaries → xlings-res/mcpp (GitHub + GitCode) so XLINGS_RES
   #      downloads resolve on every platform (incl. the CN/GitCode path);
   #   ② open a PR against openxlings/xim-pkgindex bumping mcpp to this version
   #      (a maintainer merges it — index git source is not on the critical path).
-  # Best-effort / non-blocking: a failure here never fails the release.
+  # These publication steps are required for ecosystem completeness: their
+  # failure leaves the GitHub Release object available but keeps this workflow
+  # red, so post-release verification cannot report a complete release.
   # Shared vendored scripts live in .github/tools/ (kept in sync with xlings).
   publish-ecosystem:
-    needs: [build-release, build-linux-aarch64, build-macos, build-windows]
+    needs: release-manifest
     runs-on: ubuntu-latest
     # A4 hardening: a single stuck upload once held this job >1h (6h default
     # ceiling). The mirror script has per-file timeouts and (post-0.0.89)

docs/09-release.md

@@ -41,11 +41,48 @@ tag from `mcpp.toml`) does all of this:
 ```
 build ×4 (linux x86_64 / linux aarch64 / macOS ARM64 / Windows x64)
   → GitHub Release v<version> with tarballs + .sha256 sidecars
+  → recompute every payload hash and publish immutable mcpp-release.json
   → mirror to xlings-res/mcpp on BOTH GitHub and GitCode
   → open the version-bump PR against openxlings/xim-pkgindex
   → workflow_run hook fires ci-fresh-install
 ```
 
+### 2.1 The immutable release manifest
+
+`release-manifest` waits for all four platform upload jobs. It downloads the
+final non-draft, non-prerelease GitHub Release, recomputes each versioned
+platform payload's SHA256, verifies the corresponding `.sha256` sidecar, and
+publishes `mcpp-release.json` schema 1:
+
+```json
+{
+  "schema": 1,
+  "version": "<version>",
+  "tag": "v<version>",
+  "commit": "<full-tag-commit>",
+  "assets": [
+    {
+      "platform": "linux",
+      "arch": "x86_64",
+      "name": "mcpp-<version>-linux-x86_64.tar.gz",
+      "sha256": "<recomputed-sha256>"
+    }
+  ]
+}
+```
+
+The array is sorted by platform, architecture, and name. It contains every
+versioned platform payload, including the required Linux x86_64, Linux aarch64,
+macOS ARM64, and Windows x86_64 assets. Versionless aliases and the source
+archive are intentionally not desired-state rows.
+
+The workflow then downloads the public release again, regenerates the manifest,
+and requires a byte-for-byte match. A workflow rerun accepts an existing
+manifest only when it is already byte-identical; it never overwrites different
+bytes for the same tag. Downstream release consumers (notably the `mcpp-bin`
+AUR reconciler) must consume this manifest instead of guessing completeness
+from a moving workspace or from a subset of release assets.
+
 Two steps are **not** automated:
 
 - **merging the xim-pkgindex bump PR** — a maintainer does it. Until it lands,
@@ -71,6 +108,28 @@ curl -fsSL -o /tmp/p.tgz "https://github.com/xlings-res/mcpp/releases/download/$
 sha256sum /tmp/p.tgz   # compare against pkgs/m/mcpp.lua in xim-pkgindex
 ```
 
+To repeat the release gate locally against the public GitHub inventory:
+
+```bash
+V=<version>
+TAG="v$V"
+AUDIT=$(mktemp -d)
+mkdir -p "$AUDIT/assets"
+gh api "repos/mcpp-community/mcpp/releases/tags/$TAG" > "$AUDIT/release.json"
+gh release download "$TAG" -R mcpp-community/mcpp --dir "$AUDIT/assets"
+python3 scripts/release/generate_manifest.py \
+  --release-json "$AUDIT/release.json" \
+  --assets-dir "$AUDIT/assets" \
+  --version "$V" \
+  --tag "$TAG" \
+  --commit "$(git rev-list -n 1 "$TAG")" \
+  --output "$AUDIT/expected.json"
+cmp "$AUDIT/assets/mcpp-release.json" "$AUDIT/expected.json"
+```
+
+This command recomputes payload hashes; it does not copy hashes out of the
+published manifest or blindly trust the sidecars.
+
 Then a real install, in a **clean-room `XLINGS_HOME`** — never the machine's own
 `~/.xlings`, which can mask a broken index with cached state:
 
@@ -163,7 +222,8 @@ would again let the index guard and the installed version drift apart.
 [ ] `bash .github/tools/check_version_pins.sh` passes (verifies `mcpp.toml` = `MCPP_VERSION`, and `.xlings.json` is not newer)
 [ ] merge to main, CI green
 [ ] gh workflow run release.yml --ref main
-[ ] release.yml green (4 builds + publish-ecosystem)
+[ ] release.yml green (4 builds + immutable manifest + publish-ecosystem)
+[ ] downloaded mcpp-release.json regenerates byte-identically from public assets
 [ ] mirrors serve all four platforms on BOTH hosts, sha256 recomputed
 [ ] merge the xim-pkgindex bump PR
 [ ] clean-room XLINGS_HOME: xlings install mcpp@<version> succeeds

docs/zh/09-release.md

@@ -37,11 +37,44 @@ POSIX `sh`/dash 解析不了 —— `sh check_version_pins.sh` 会在第 95 行
 ```
 四平台构建（linux x86_64 / linux aarch64 / macOS ARM64 / Windows x64）
   → GitHub Release v<version>，含 tarball 与 .sha256 边车文件
+  → 重新计算每个载荷的哈希并发布不可变 mcpp-release.json
   → 镜像到 xlings-res/mcpp 的 GitHub 与 GitCode 双端
   → 向 openxlings/xim-pkgindex 开版本 bump PR
   → workflow_run 钩子触发 ci-fresh-install
 ```
 
+### 2.1 不可变 release manifest
+
+`release-manifest` 会等待四个平台上传 job 全部结束，然后下载最终的非 draft、
+非 prerelease GitHub Release，重新计算每个带版本平台载荷的 SHA256，校验对应的
+`.sha256` 边车文件，并发布 schema 1 的 `mcpp-release.json`：
+
+```json
+{
+  "schema": 1,
+  "version": "<version>",
+  "tag": "v<version>",
+  "commit": "<tag-所指完整-commit>",
+  "assets": [
+    {
+      "platform": "linux",
+      "arch": "x86_64",
+      "name": "mcpp-<version>-linux-x86_64.tar.gz",
+      "sha256": "<重新计算的-sha256>"
+    }
+  ]
+}
+```
+
+数组按平台、架构、名称排序，包含所有带版本的平台载荷；其中 Linux x86_64、
+Linux aarch64、macOS ARM64、Windows x86_64 四项是硬性要求。无版本别名和源码包
+刻意不进入 desired-state 行。
+
+workflow 随后会再次下载公开 release、重新生成 manifest，并要求逐字节一致。
+重跑 workflow 时，已有 manifest 只有在字节完全相同时才会被接受；同一 tag 下
+绝不以不同内容覆盖。下游发布消费者（尤其 `mcpp-bin` AUR reconciler）必须消费
+该 manifest，不能从会变化的工作区或部分 release 资产猜测发布是否完整。
+
 两步**没有**自动化：
 
 - **合并 xim-pkgindex 的 bump PR** —— 由维护者完成。在它落地之前，发布出来的版本
@@ -66,6 +99,27 @@ curl -fsSL -o /tmp/p.tgz "https://github.com/xlings-res/mcpp/releases/download/$
 sha256sum /tmp/p.tgz   # 与 xim-pkgindex 的 pkgs/m/mcpp.lua 对照
 ```
 
+要在本地针对 GitHub 公开资产重放 release gate：
+
+```bash
+V=<version>
+TAG="v$V"
+AUDIT=$(mktemp -d)
+mkdir -p "$AUDIT/assets"
+gh api "repos/mcpp-community/mcpp/releases/tags/$TAG" > "$AUDIT/release.json"
+gh release download "$TAG" -R mcpp-community/mcpp --dir "$AUDIT/assets"
+python3 scripts/release/generate_manifest.py \
+  --release-json "$AUDIT/release.json" \
+  --assets-dir "$AUDIT/assets" \
+  --version "$V" \
+  --tag "$TAG" \
+  --commit "$(git rev-list -n 1 "$TAG")" \
+  --output "$AUDIT/expected.json"
+cmp "$AUDIT/assets/mcpp-release.json" "$AUDIT/expected.json"
+```
+
+这个命令会重新计算载荷哈希，不会从已发布 manifest 抄哈希，也不会盲信边车文件。
+
 然后在 **clean-room `XLINGS_HOME`** 里真装一次 —— 绝不要用本机的 `~/.xlings`，
 它的缓存状态会把一个坏掉的索引掩盖过去：
 
@@ -133,7 +187,8 @@ $(find "$XLINGS_HOME" -name mcpp -type f -path '*/bin/*' | head -1) --version
 [ ] `bash .github/tools/check_version_pins.sh` 通过（校验 `mcpp.toml` = `MCPP_VERSION`，且 `.xlings.json` 未领先）
 [ ] 合入 main，CI 全绿
 [ ] gh workflow run release.yml --ref main
-[ ] release.yml 全绿（4 个构建 + publish-ecosystem）
+[ ] release.yml 全绿（4 个构建 + 不可变 manifest + publish-ecosystem）
+[ ] 下载的 mcpp-release.json 能从公开资产逐字节重新生成
 [ ] 双端都服务四个平台，sha256 重新算过
 [ ] 合并 xim-pkgindex 的 bump PR
 [ ] clean-room XLINGS_HOME：xlings install mcpp@<version> 成功