cut-release: regenerate candidate before freezing it, not after

script/cut-release.sh is what rainix-tag-release runs as its snapshot-generate-cmd,
so this is the code that will cut this repo's first real release (rain.factory#46
step 3). It froze the numbered snapshot from the committed candidate and only
then re-ran BuildPointers.

That order is silently wrong whenever the committed candidate has drifted from
the source. The copy freezes the stale bytes into src/generated/<tag>/, which the
frozen-snapshots-append-only gate then protects forever, and the regeneration
immediately moves candidate on to the real ones. The release publishes a
LibCloneFactoryDeploy aliasing the new address while permanently recording the
old one as what that version shipped.

Nothing downstream catches it. testCandidateSelfConsistent compares the
REGENERATED candidate to the source, so it is green either way, and no test
compares a numbered dir to candidate. The append-only gate only sees an added
dir. The failure is invisible until someone tries to reproduce the release.

Reordered so the frozen dir is a copy of a candidate already known to match the
source, with forge fmt also moved ahead of the copy so the two are byte-identical
rather than differing by formatting. Added a diff -r assertion after the copy so
the property is checked, not assumed.

No behaviour change when candidate is already fresh, which is the normal case CI
enforces on main. This is the abnormal case: tagging while main is red.

Docs corrected to match — CLAUDE.md stated the old order in two places.

Author: thedavidmeister

CLAUDE.md

@@ -81,8 +81,10 @@ as the `rain-factory` Soldeer dependency, so they are read under
   tag. Never regenerated.
 - `script/BuildPointers.sol` — Regenerates `candidate` and the
   `LibCloneFactoryDeploy` alias. Never writes a numbered snapshot.
-- `script/cut-release.sh` — Freezes `candidate` as `src/generated/<tag>/` at
-  release time. The only thing that creates a numbered snapshot.
+- `script/cut-release.sh` — Regenerates `candidate`, then freezes it as
+  `src/generated/<tag>/` at release time. The only thing that creates a numbered
+  snapshot. Regenerating first is what makes the frozen record equal to the pins
+  the release actually publishes.
 - `script/Deploy.sol` — The Zoltu deploy script.
 
 ## Solidity Conventions
@@ -125,10 +127,10 @@ uses the **rolling-candidate** model:
   `rain-factory-deploy` revisions.
 - A human pushes a `sol-v<version>` tag, which runs `rainix-tag-release`: it
   writes the version from the tag into `foundry.toml`, runs
-  `bash script/cut-release.sh` (which copies `candidate` to
-  `src/generated/<tag>/`, then regenerates), verifies the live chains match the
-  pins with `forge test`, publishes `rain-factory-deploy` to Soldeer, and
-  commits the new snapshot back to `main`.
+  `bash script/cut-release.sh` (which regenerates `candidate`, then copies it to
+  `src/generated/<tag>/`), verifies the live chains match the pins with
+  `forge test`, publishes `rain-factory-deploy` to Soldeer, and commits the new
+  snapshot back to `main`.
 - The on-chain deploy happens **before** tagging, via the manual dispatch above;
   `rainix-tag-release` never broadcasts, it only attests.
 - Existing `src/generated/<tag>/` snapshots are frozen: a release adds a new tag

script/cut-release.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # SPDX-License-Identifier: LicenseRef-DCL-1.0
 # SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
-# Freeze the rolling `candidate` snapshot as a numbered release snapshot, then
-# regenerate the deploy pointer lib.
+# Regenerate the rolling `candidate` snapshot, then freeze it as a numbered
+# release snapshot.
 #
 # Invoked by rainix-tag-release as its `snapshot-generate-cmd`, AFTER the
 # reusable has resolved the release version from the pushed `sol-vX.Y.Z` tag and
@@ -13,8 +13,8 @@
 # source compiles to (regenerated every BuildPointers run). A numbered snapshot
 # (`0_1_5/`, …) is a FROZEN copy of `candidate` taken at the instant a tag
 # releases it — it never changes again (the frozen-snapshots-append-only gate
-# enforces this). This script performs that copy, then re-runs BuildPointers so
-# the pointer lib is regenerated on top of the freshly cut tree.
+# enforces this). This script regenerates `candidate` from the current source and
+# then performs that copy.
 set -euo pipefail
 
 VERSION="$(grep -m1 -E '^version = ' foundry.toml | sed -E 's/^version = "([^"]+)"/\1/')"
@@ -43,11 +43,30 @@ if [ -d "src/generated/${TAG}" ]; then
   exit 1
 fi
 
+# Regenerate FIRST, freeze SECOND. The numbered dir must record what this release
+# actually publishes, and what it publishes is `candidate` — the pin lib aliases
+# it — so the copy has to come from a `candidate` already known to match the
+# current source.
+#
+# The other order is silently wrong whenever the committed `candidate` has
+# drifted from the source: the copy freezes the stale bytes into a dir the
+# append-only gate then protects forever, while this regeneration moves
+# `candidate` on to the real ones. Nothing downstream catches it —
+# `testCandidateSelfConsistent` checks the *regenerated* `candidate` against the
+# source, and no test compares a numbered dir to `candidate` — so the release
+# publishes one address and permanently records another.
+#
+# `forge fmt` also runs before the copy, so the frozen dir is byte-identical to
+# `candidate` rather than to its pre-format form.
+forge script ./script/BuildPointers.sol
+forge fmt
+
 echo "cut-release: freezing candidate -> src/generated/${TAG}"
 cp -r src/generated/candidate "src/generated/${TAG}"
 
-# Regenerate candidate (idempotent — source unchanged) and the pointer lib. The
-# lib keeps pointing at `candidate`: "current" never advances to the numbered
-# dir, which is only a historical record of what this release shipped.
-forge script ./script/BuildPointers.sol
-forge fmt
+# The point of the ordering above, asserted rather than assumed: the frozen
+# record and the published pin are the same bytes.
+if ! diff -r src/generated/candidate "src/generated/${TAG}"; then
+  echo "cut-release: src/generated/${TAG} does not match src/generated/candidate after the copy" >&2
+  exit 1
+fi