feat(scripts): one-shot release backfill to the public mirror (all tags, newest 10 binaries)

.github/workflows/build.yml

@@ -101,6 +101,10 @@ jobs:
           bash -n scripts/tests/mirror-publish-workflow-verify.sh
           bash -n scripts/publish-guard.sh
           bash -n scripts/publish-mirror.sh
+          shellcheck --shell=bash --severity=warning scripts/backfill-releases.sh
+          shellcheck --shell=bash --severity=warning scripts/tests/backfill-releases-verify.sh
+          bash -n scripts/backfill-releases.sh
+          bash -n scripts/tests/backfill-releases-verify.sh
       # format.sh's own fail-closed properties. Formatters are stubbed, so this is
       # hermetic and needs no Go toolchain — which is why it lives in this job
       # rather than Lint. It exists because the first cut of format.sh reported
@@ -152,6 +156,18 @@ jobs:
       # out of the YAML and executed with `gh` shimmed, so this is hermetic.
       - name: Mirror-publish workflow harness (step bodies / shape / mutations)
         run: bash scripts/tests/mirror-publish-workflow-verify.sh
+      # The one-shot historical backfill (scripts/backfill-releases.sh): dry-run
+      # writes nothing, --apply makes exactly the expected writes and a second
+      # --apply none, binaries stop at the BINARY_KEEP boundary, a binary that
+      # disagrees with SHA256SUMS or a forbidden string in a body refuses by
+      # name, a failed read is could-not-tell. `gh` is a recording fake serving
+      # fixtures, so this is hermetic. The second step breaks one rule per copy
+      # of the script and demands the same suite go red — a rule the suite
+      # cannot see reddens the build.
+      - name: Release-backfill harness (zero-write dry-run / idempotent / fail-closed)
+        run: bash scripts/tests/backfill-releases-verify.sh
+      - name: Release-backfill harness — mutations (every anchored rule is load-bearing)
+        run: bash scripts/tests/backfill-releases-verify.sh --mutations
 
   test:
     timeout-minutes: 15

scripts/RELEASE_CHECKLIST.md

@@ -48,6 +48,44 @@ have to reverse-engineer the surface area on release day.
    pinned to the mirror's current default-branch head — the mirror's
    default branch keeps the last stable release.
 
+8. Releases that predate the mirror are carried over ONCE, by hand, with
+   `scripts/backfill-releases.sh` (the workflow only publishes releases
+   cut after it exists). The decision it implements: every published
+   release gets its tag, its GitHub release and its text assets
+   (`install.sh`, `install.ps1`, `SHA256SUMS`, anything else SHA256SUMS
+   does not list); the binaries and their `.sig`/`.cert` only for the
+   newest `BINARY_KEEP` releases (default 10) — older pinned binary
+   URLs 404 on the mirror, and the answer is "re-run the installer".
+   Prereleases are skipped unless `--include-prerelease`. Mirror tags
+   are annotated RELEASE MARKERS on the mirror's default-branch head,
+   carrying the original date and message — the mirror has no source
+   commit to point at, and the annotation says so. Release notes are
+   the same fixed text the workflow writes (`--notes fixed`, the
+   default) plus a footer naming the original publish date — the
+   historical bodies are GitHub's generated pull-request lists, and
+   nearly every one carries strings the guard's report tier counts,
+   which the mirror should not repeat. `--notes source` carries the
+   source body instead, as an explicit opt-in. Every text asset and
+   every release body goes through `publish-guard.sh` first; every
+   binary is checked against the source's `SHA256SUMS`; anything
+   already on the mirror with the same SHA256 is skipped, so a re-run
+   writes nothing. Dry-run is the default:
+
+   ```bash
+   MIRROR_REPO=<mirror name> scripts/backfill-releases.sh            # plan
+   MIRROR_REPO=<mirror name> scripts/backfill-releases.sh --apply    # write
+   # resume after a failure, or redo one release:
+   MIRROR_REPO=<mirror name> scripts/backfill-releases.sh --apply --from-tag vX.Y.Z
+   MIRROR_REPO=<mirror name> scripts/backfill-releases.sh --apply --only-tag vX.Y.Z
+   ```
+
+   Needs `gh` (token with write on the mirror), `jq`, `gitleaks`; set
+   `BACKFILL_EXTRA_FORBIDDEN` to a file with the private needle list
+   the workflow gets from its secret, or the string scan runs without
+   them. Exit 1 means at least one release was refused (the table says
+   which and why); exit 2 means a read did not complete and nothing was
+   written. The script's header carries the full contract.
+
 GitHub Releases plus the cosign-verified `install.sh` are the
 install path — a Homebrew tap and the `install.tracebloc.io`
 vanity URL were considered and dropped