ci: derive the fresh-install version instead of hand-editing it, and document releasing (#321)

`ci-fresh-install.yml` carried MCPP_PIN as a hardcoded literal that a maintainer
had to bump on every release. It was never the same thing as the `.xlings.json`
pin it was kept equal to: MCPP_PIN is the version UNDER TEST — always the newest
published release — while `.xlings.json` is the version BOOTSTRAPPED FROM, which
only has to be a released mcpp that can build the current tree.

The workflow already computed the right answer. Its `wait-index` guard queries
the releases API for the newest tag, waits for xim-pkgindex to track it — and
then discards it, while the install jobs used the literal. That gap is exactly
the #265 failure: the guard reported "index tracks 0.0.102" and the jobs
installed 0.0.100 ten seconds later, meeting an index whose floor was 0.0.101.

wait-index now exports the derived version and all four install jobs consume it.
Both properties the literal was protecting hold, and one of them structurally:

  explicit version  a derived string is as explicit as a literal, so a lagging
                    runner index still fails loudly with `version not found`
                    rather than silently testing an older binary
  one source        the guard and the jobs cannot disagree about which version
                    is under test, because there is only one value

Deriving happens on every trigger, not just post-release — "the newest published
release" is the version under test on cron and manual runs too. Only the WAIT
stays conditional, since only a post-release run can legitimately race the index.
A non-numeric or empty API result is refused, because `mcpp@` with an empty
version degrades into bare `mcpp` — straight back to "newest in the runner's
index copy".

check_version_pins.sh loses the now-meaningless "both pin sites agree" invariant
and gains a guard against a literal MCPP_PIN reappearing (probe-tested: it fails
when the literal is restored, passes when it is not).

Also adds docs/09-release.md (+ zh), which did not exist. The release process
lived in commit messages and workflow comments only. It documents the two version
groups, what the pipeline automates and what it does not, how to verify a release
without trusting a sha256 sidecar, and the index's CDN propagation lag.

It also corrects 3b1cb6b, which claimed "the index no longer serves .1" and made
the bootstrap bump look mandatory. That diagnosis is wrong — 2026.7.29.1 installs
fine from the current index, which retains all 105 published versions; the real
cause was a stale local index copy. The bump is a useful check (a green round
proves the new release can self-host), not a prerequisite. The one hard rule is
direction: never pin a version that is not yet installable.

Co-authored-by: sunrisepeak <speakshen@163.com>

Author: speak-agent

.github/tools/check_version_pins.sh

@@ -104,32 +104,42 @@ v_src=$(grep -oE 'MCPP_VERSION[[:space:]]*=[[:space:]]*"[^"]+"' src/toolchain/fi
         | grep -oE '"[^"]+"' | tr -d '"' | head -1)
 v_xl=$(grep -oE '"mcpp"[[:space:]]*:[[:space:]]*"[^"]+"' .xlings.json \
        | grep -oE '"[^"]+"$' | tr -d '"' | head -1)
-v_pin=$(grep -oE "MCPP_PIN:[[:space:]]*'[^']+'" .github/workflows/ci-fresh-install.yml \
-        | grep -oE "'[^']+'" | tr -d "'" | head -1)
-
-note "mcpp version: building=$v_toml (fingerprint=$v_src)  bootstrap pin=$v_xl (MCPP_PIN=$v_pin)"
+note "mcpp version: building=$v_toml (fingerprint=$v_src)  bootstrap pin=$v_xl"
 
 for n in "mcpp.toml:$v_toml" "src/toolchain/fingerprint.cppm:$v_src" \
-         ".xlings.json:$v_xl" "ci-fresh-install.yml MCPP_PIN:$v_pin"; do
+         ".xlings.json:$v_xl"; do
   [ -n "${n##*:}" ] || bad "${n%:*} — could not read the mcpp version"
 done
 
+# ci-fresh-install.yml used to carry a SECOND hand-edited copy of the bootstrap
+# pin (MCPP_PIN), and this script enforced that the two stayed equal. They are
+# not the same thing and never were: MCPP_PIN is the version UNDER TEST (always
+# the newest published release), while .xlings.json is the version BOOTSTRAPPED
+# FROM (any released mcpp that can build the current tree). Keeping them equal
+# forced a manual edit on every release for a value the workflow could derive —
+# and the workflow's own index guard was already deriving it from the releases
+# API and discarding it. MCPP_PIN is now that derived value, so there is no
+# second site left to agree with. Guard against a silent regression to a
+# literal:
+if grep -qE "MCPP_PIN:[[:space:]]*['\"]?[0-9]" .github/workflows/ci-fresh-install.yml; then
+  bad "ci-fresh-install.yml hardcodes MCPP_PIN again — it must stay derived from
+       wait-index's releases-API lookup, or the index guard and the install jobs
+       can once more disagree about which version is under test (#265)"
+fi
+
 # (a) The version being BUILT: mcpp.toml and the compiled-in constant are the
 #     same number by definition — release.yml derives the tag from the former
 #     and the smoke test greps the latter out of `mcpp --version`.
 [ -z "$v_src" ] || [ "$v_src" = "$v_toml" ] \
   || bad "src/toolchain/fingerprint.cppm has '$v_src' but mcpp.toml has '$v_toml'"
 
-# (b) The version BOOTSTRAPPED FROM: both sites name a mcpp that is already
-#     published, so they must agree with each other — but they are NOT required
-#     to equal the version being built. They deliberately lag, and are bumped in
-#     a separate commit AFTER the release exists in xim-pkgindex (see the
-#     MCPP_PIN comment in ci-fresh-install.yml). Requiring equality here is what
-#     an earlier revision of this script got wrong: it sent CI to install a
+# (b) The version BOOTSTRAPPED FROM (.xlings.json) names a mcpp that is already
+#     published, and is NOT required to equal the version being built. It
+#     deliberately lags, and is bumped in a separate commit AFTER the release
+#     exists in xim-pkgindex (see docs/09-release.md). Requiring equality here is
+#     what an earlier revision of this script got wrong: it sent CI to install a
 #     version that did not exist yet, and every job died with
 #     `package 'mcpp@<unreleased>' not found`.
-[ -z "$v_xl" ] || [ -z "$v_pin" ] || [ "$v_xl" = "$v_pin" ] \
-  || bad ".xlings.json pins '$v_xl' but ci-fresh-install.yml MCPP_PIN is '$v_pin' — both bootstrap the same released mcpp"
 
 # (c) …and the bootstrap pin must never run AHEAD of the version being built.
 #     Four-key numeric sort, so the date scheme orders correctly (a plain

.github/workflows/ci-fresh-install.yml

@@ -31,16 +31,31 @@ concurrency:
   group: ci-fresh-install
   cancel-in-progress: false # use false to test in PRs, true to only test released mcpp
 
-# Version under test. Bare `xlings install mcpp` resolves "newest in the
-# runner's index copy", which is NOT the same source the wait-index job
-# polls (raw.githubusercontent.com) — on 2026-07-21 the guard reported
-# "index tracks 0.0.102" and the jobs still installed 0.0.100 ten seconds
-# later, which then met an index whose floor was 0.0.101 (#265). Pinning
-# makes the version explicit: if the index cannot serve it yet, the job
-# fails with `version not found` instead of silently testing an older
-# binary. Bump together with the .xlings.json workspace pin at release.
-env:
-  MCPP_PIN: '2026.7.30.3'
+# The version under test is DERIVED, once, by the resolve-version job below,
+# and every install job consumes that one value.
+#
+# Two things had to hold, and a hardcoded pin only bought the first:
+#
+#  1. It must be an explicit version string. Bare `xlings install mcpp`
+#     resolves "newest in the runner's index copy", so a runner whose copy
+#     lags silently tests an OLDER binary and reports green. Naming the
+#     version makes a lagging index fail loudly with `version not found`.
+#
+#  2. The version the index guard waits for must be the version the jobs
+#     install. On 2026-07-21 they disagreed: the guard reported "index tracks
+#     0.0.102" and the jobs installed 0.0.100 ten seconds later, which then met
+#     an index whose floor was 0.0.101 (#265). The guard already derived the
+#     real answer from the releases API and threw it away.
+#
+# Deriving once and feeding both satisfies (1) and makes (2) structurally
+# impossible, instead of relying on a human to keep two hand-edited numbers in
+# step with a third that moves on its own. `xlings install mcpp@<derived>` is
+# every bit as explicit as `mcpp@<literal>`.
+#
+# NOT to be confused with the .xlings.json workspace pin, which this used to be
+# kept equal to. That one is the BOOTSTRAP compiler for the self-host builds and
+# has a different requirement — it must be a released mcpp that can build the
+# CURRENT source tree — so it stays hand-maintained. See docs/09-release.md.
 
 jobs:
   # ──────────────────────────────────────────────────────────────────
@@ -56,11 +71,31 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     timeout-minutes: 20
+    outputs:
+      version: ${{ steps.resolve.outputs.version }}
     steps:
+      # Derive on EVERY trigger, not just post-release. "The newest published
+      # release" is the version under test whether we got here from the release
+      # pipeline, from cron, or by hand — only the WAIT below is specific to a
+      # post-release run, because only then can the index legitimately lag.
+      - name: Resolve the version under test (newest published release)
+        id: resolve
+        run: |
+          VER=$(curl -fsSL "https://api.github.com/repos/mcpp-community/mcpp/releases/latest" \
+                | python3 -c "import json,sys; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
+          # A blank version would silently degrade `mcpp@$VER` into bare `mcpp`,
+          # i.e. straight back to "newest in the runner's index copy" — the exact
+          # failure this job exists to prevent. Refuse instead.
+          case "$VER" in
+            ''|*[!0-9.]*) echo "::error::could not resolve a version from the releases API (got '$VER')"; exit 1 ;;
+          esac
+          echo "version=$VER" >> "$GITHUB_OUTPUT"
+          echo "version under test: $VER"
       - name: Wait for xim-pkgindex to track the released mcpp
         if: ${{ github.event_name == 'workflow_run' }}
+        env:
+          VER: ${{ steps.resolve.outputs.version }}
         run: |
-          VER=$(curl -fsSL "https://api.github.com/repos/mcpp-community/mcpp/releases/latest" | python3 -c "import json,sys; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
           echo "released: $VER — waiting for index..."
           for i in $(seq 1 30); do
             if curl -fsSL "https://raw.githubusercontent.com/openxlings/xim-pkgindex/main/pkgs/m/mcpp.lua" | grep -q "\"$VER\""; then
@@ -81,6 +116,9 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 60
     env:
+      # The one derived value (see the header comment): every install job names
+      # the SAME version the index guard waited for, so the two cannot disagree.
+      MCPP_PIN: ${{ needs.wait-index.outputs.version }}
       # Verbose every mcpp invocation — fresh-install is the cold index/sandbox
       # bootstrap path, exactly where extra diagnostics matter (src/cli.cppm).
       MCPP_VERBOSE: "1"
@@ -217,6 +255,9 @@ jobs:
             image: debian:11
             setup: apt-get update && apt-get -y install curl bash tar gzip xz-utils git ca-certificates binutils findutils file
     env:
+      # The one derived value (see the header comment): every install job names
+      # the SAME version the index guard waited for, so the two cannot disagree.
+      MCPP_PIN: ${{ needs.wait-index.outputs.version }}
       XLINGS_NON_INTERACTIVE: '1'
       HOME: /root
     steps:
@@ -277,6 +318,10 @@ jobs:
     # independence (this image has no sha256sum; macos-15 does).
     runs-on: macos-14
     timeout-minutes: 30
+    env:
+      # The one derived value (see the header comment): every install job names
+      # the SAME version the index guard waited for, so the two cannot disagree.
+      MCPP_PIN: ${{ needs.wait-index.outputs.version }}
     steps:
       - uses: actions/checkout@v4
 
@@ -337,6 +382,10 @@ jobs:
     if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: windows-latest
     timeout-minutes: 30
+    env:
+      # The one derived value (see the header comment): every install job names
+      # the SAME version the index guard waited for, so the two cannot disagree.
+      MCPP_PIN: ${{ needs.wait-index.outputs.version }}
     steps:
       - uses: actions/checkout@v4
 

docs/09-release.md

@@ -0,0 +1,145 @@
+# 09 — Releasing mcpp
+
+How a release of **mcpp itself** reaches users. This is maintainer-facing; for
+packaging *your own* project see [02 — Packaging for Release](02-pack-and-release.md).
+
+Until now this process lived only in commit messages and workflow comments. One
+of those commit messages contains a misdiagnosis that is corrected in §5.
+
+## 1. The four version sites are two groups
+
+| Site | Group | Moves when |
+|---|---|---|
+| `mcpp.toml` `[package].version` | **being built** | you start work on a new version |
+| `src/toolchain/fingerprint.cppm` `MCPP_VERSION` | **being built** | same commit as above (compiled-in copy) |
+| `.xlings.json` `[workspace].mcpp` | **bootstrapped from** | separately, *after* a release is installable |
+| `ci-fresh-install.yml` `MCPP_PIN` | ~~bootstrapped from~~ | **nothing — it is derived at run time** (§4) |
+
+`.github/tools/check_version_pins.sh` enforces what is left mechanically. The two
+"being built" sites must be equal; the bootstrap pin must never be **newer** than
+the version being built.
+
+The two groups are deliberately allowed to differ. Bumping them together is what
+an earlier revision of the pin checker required, and it sent every CI job to
+install a version that did not exist yet.
+
+## 2. The pipeline
+
+`release.yml` (tag push, or `workflow_dispatch` with no input, which derives the
+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
+  → 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
+```
+
+Two steps are **not** automated:
+
+- **merging the xim-pkgindex bump PR** — a maintainer does it. Until it lands,
+  the released version is downloadable but not installable via `xlings install`.
+- **bumping `.xlings.json`** — see §4.
+
+## 3. Verifying a release
+
+The mirror script verifies its own uploads, but the checks worth doing by hand
+are the ones that do not trust a sidecar:
+
+```bash
+V=<version>
+# both hosts serve every platform, byte-exact
+for a in linux-x86_64.tar.gz linux-aarch64.tar.gz macosx-arm64.tar.gz windows-x86_64.zip; do
+  for h in github.com gitcode.com; do
+    curl -fsSL -o /dev/null -w "$h $a %{http_code} %{size_download}\n" \
+      "https://$h/xlings-res/mcpp/releases/download/$V/mcpp-$V-$a"
+  done
+done
+# the index's sha256 values match the payloads (recompute; do not read the sidecar)
+curl -fsSL -o /tmp/p.tgz "https://github.com/xlings-res/mcpp/releases/download/$V/mcpp-$V-linux-x86_64.tar.gz"
+sha256sum /tmp/p.tgz   # compare against pkgs/m/mcpp.lua in xim-pkgindex
+```
+
+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:
+
+```bash
+export XLINGS_HOME=$(mktemp -d)
+xlings update
+xlings install mcpp@$V -y
+$(find "$XLINGS_HOME" -name mcpp -type f -path '*/bin/*' | head -1) --version
+```
+
+**Index propagation is not instant.** `xim-pkgindex` reaches clients as a CDN
+artifact, not a git clone, so a freshly merged bump is invisible for a while
+(measured at ~5 min on 2026-07-30; the documented worst case is ~40 min). A
+clean-room that still reports the old `latest` has not failed — it has not caught
+up. `ci-fresh-install`'s `wait-index` job encodes exactly this with a bounded
+15-minute wait.
+
+## 4. The bootstrap pin: what it is, and when to bump it
+
+`.xlings.json`'s `[workspace].mcpp` is the **starting point of self-hosting** —
+the released mcpp that `xlings install mcpp` puts in the workspace so CI can build
+mcpp from source. Its only requirement is that it can build the **current** tree.
+
+**It does not have to move with every release.** The index retains every
+published version (105 entries at the time of writing, back to the 0.0.x series),
+so an older pin keeps resolving indefinitely — verified by installing a
+two-releases-old version against the current index.
+
+Bumping it anyway is reasonable and is what this repository does in practice: a
+green CI round on the bumped pin is a direct proof that the new release can build
+mcpp itself on every platform. Treat it as a *useful check*, not a prerequisite.
+
+**The one hard constraint is direction**: the pin must never name a version that
+is not yet installable. Bump it only after the release is published, mirrored,
+**and merged into xim-pkgindex** — otherwise every CI job fails with
+`package 'mcpp@<unreleased>' not found`. `check_version_pins.sh` enforces the
+weaker "never newer than the version being built"; the index condition is on you.
+
+## 5. `MCPP_PIN` is derived, and why that matters
+
+`ci-fresh-install.yml` used to carry a second hand-edited copy of the pin. It was
+never the same thing: `MCPP_PIN` is the version **under test** — always the newest
+published release — while `.xlings.json` is the version **bootstrapped from**.
+
+It is now derived once, by the `wait-index` job, from the releases API, and every
+install job consumes that single output. Two properties had to hold, and the
+hardcoded literal only bought the first:
+
+1. **The version must be explicit.** Bare `xlings install mcpp` resolves "newest
+   in the runner's index copy", so a lagging runner silently tests an *older*
+   binary and reports green. Naming the version makes a lagging index fail loudly
+   with `version not found`. A derived string is every bit as explicit as a
+   literal one.
+2. **The guard and the jobs must name the same version.** On 2026-07-21 they did
+   not: the index guard reported "index tracks 0.0.102" while the jobs installed
+   0.0.100 ten seconds later, meeting an index whose floor was 0.0.101 (#265).
+   The guard was already deriving the right answer and throwing it away. Feeding
+   both from one value makes that disagreement structurally impossible.
+
+`check_version_pins.sh` fails if a literal `MCPP_PIN:` reappears.
+
+> **Correction.** Commit `3b1cb6b` ("bootstrap pin -> 2026.7.29.2") states *"the
+> index no longer serves .1"* and quotes `version '2026.7.29.1' not found`. That
+> diagnosis is wrong: `2026.7.29.1` installs fine from the current index. The real
+> cause was a **stale local index copy** — the same propagation lag described in
+> §3, seen from the other side. Nothing about a release removes older versions,
+> and no reasoning should be built on the idea that it does.
+
+## 6. Checklist
+
+```
+[ ] version bumped in mcpp.toml + fingerprint.cppm (one commit)
+[ ] CHANGELOG entry
+[ ] bash .github/tools/check_version_pins.sh
+[ ] merge to main, CI green
+[ ] gh workflow run release.yml --ref main
+[ ] release.yml green (4 builds + publish-ecosystem)
+[ ] 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
+[ ] (optional) bump .xlings.json — only now, never earlier
+```

docs/README.md

@@ -11,6 +11,7 @@
 - [06 - Workspaces](06-workspace.md)
 - [07 - build.mcpp Build Program](07-build-mcpp.md)
 - [08 - Toolchain Internals](08-toolchain-internals.md)
+- [09 - Releasing mcpp](09-release.md)
 
 ## Specifications