From f3984ff96451eddbefd06a29eb93a7445819013b Mon Sep 17 00:00:00 2001
From: William Aaron Cheung <git@troublor.xyz>
Date: Thu, 10 Sep 2026 16:45:32 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat(release):=20snapshot=20publish=20?=
 =?UTF-8?q?=E2=80=94=20build=20one=20commit,=20no=20tag,=20no=20Release?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the snapshot flow for components that deployments pin by commit:
the release-snapshot action (stage resolve: ref → commit with a branch
guard, registry version = commit, path = <profile>/<label>; stage
summary: uploads table, manifest entry, optional commit statuses), the
snapshot-publish.yml workflow template, a guide section and reference
rows in RELEASE.md, and an end-to-end test job.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/actions/README.md                     |   1 +
 .github/actions/RELEASE.md                    |  34 +++-
 .github/actions/release-snapshot/README.md    | 133 ++++++++++++
 .github/actions/release-snapshot/action.yml   | 189 ++++++++++++++++++
 .github/workflows/actions-test.yml            |  74 +++++++
 .../snapshot-publish.properties.json          |   8 +
 workflow-templates/snapshot-publish.yml       | 119 +++++++++++
 7 files changed, 557 insertions(+), 1 deletion(-)
 create mode 100644 .github/actions/release-snapshot/README.md
 create mode 100644 .github/actions/release-snapshot/action.yml
 create mode 100644 workflow-templates/snapshot-publish.properties.json
 create mode 100644 workflow-templates/snapshot-publish.yml

diff --git a/.github/actions/README.md b/.github/actions/README.md
index 57ec545..696d2f7 100644
--- a/.github/actions/README.md
+++ b/.github/actions/README.md
@@ -17,6 +17,7 @@ input, output, step and error tables are generated from its `action.yml`.
 | [`release-publish`](release-publish/README.md) | [Release pipeline](RELEASE.md) | Publish a settled release. Normally runs when a `chore/release-settle-vX.Y.Z` PR merges into its release branch (or, with `commit` + `version` given, on an explicit commit that `release-settle` in `direct` mode just made): creates the annotated tag `vX.Y.Z` at the merge commit (exactly once — refuses if it exists, or if the branch moved after the settle PR was opened) and publishes the GitHub Release with the changelog section as notes. This is the only place in the release flow that creates a tag; merging the settle PR is the approval. The default branch's changelog catches up in the next release candidate PR — nothing is back-merged. The consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-publish-rust-crates`](release-publish-rust-crates/README.md) | [Release pipeline](RELEASE.md) | Publish an explicit list of workspace crates to crates.io at the release version. Verifies every listed crate's manifest version first, skips crates already published at that version (so a re-run after a partial failure finishes the rest), publishes the remainder in one `cargo publish -p … -p …` invocation — Cargo orders by dependency and waits for the index between crates (requires Cargo ≥ 1.90) — then polls crates.io until every crate reports the version. `dry_run` runs `cargo publish --dry-run`: full packaging and build verification, nothing uploaded. Run inside a job that has checked out the release tag and installed the toolchain the crates need. Never use `--workspace`: a crate without `publish = false` that was never meant to be published would go out with it. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-settle`](release-settle/README.md) | [Release pipeline](RELEASE.md) | Propose settling a release candidate: verify `commit` is the tip of the release branch and carries the expected version, generate release notes from the commits since the previous tag, write them into the changelog (stamping the date onto the candidate's `## vX.Y.Z` entry), and — in the default `pr` mode — open a `chore/release-settle-vX.Y.Z` PR onto the release branch; merging that PR is the settlement decision and release-publish then tags the merge commit once. In `direct` mode the dispatch itself is the decision, gated by the `release` environment the consumer puts on the settle job (optionally also by `settlers`); the changelog commit is pushed straight to the release branch (the app must be a bypass actor on that branch's ruleset), and release-publish runs immediately on that commit. Run as a step in a job the consumer owns; the consumer checks the repository out first (`fetch-depth: 0`, `persist-credentials: false`). Needs `gh` and `python3` on the runner. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
+| [`release-snapshot`](release-snapshot/README.md) | [Release pipeline](RELEASE.md) | The two bookends of a snapshot publish — a build of one commit pushed to the artifact registry with no tag and no GitHub Release, for components that deployments pin by commit. `stage: resolve` turns `ref` (a branch, tag or commit; empty means the run's own commit) into the coordinates the upload steps need: the full commit, and the registry `version` (the commit) and `path` (`<profile>/<label>`, e.g. `release/latest`) that match how deployment tooling addresses a snapshot. With `allowed_branches` it refuses a commit that is not reachable from one of those branches, so a dispatch cannot publish an unreviewed commit even though the environment only authorises the branch the workflow ran from. `stage: summary` writes the run summary after the uploads: where each file went, its checksum, and the manifest entry (`commit`, `version`, `profile`) a deployment repository pins; optionally it also records a commit status per package so the commit page shows what was published. Needs a checkout with history for `resolve` (the branch guard uses `merge-base`); nothing here is organisation-specific. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-upload-artifact`](release-upload-artifact/README.md) | [Release pipeline](RELEASE.md) | Upload one file to Google Artifact Registry (generic repository) or a Cloud Storage bucket, idempotently: if the destination already holds a file, its hash is compared — identical means "already there" (success, nothing uploaded), different means failure, never a silent overwrite. Every destination is an input; nothing is defaulted. Authentication is the caller's job: run `google-github-actions/auth` (service-account key or Workload Identity Federation) before this step so `gcloud` is authenticated. `dry_run` computes the checksum and checks the destination but uploads nothing. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 | [`release-verify-version`](release-verify-version/README.md) | [Release pipeline](RELEASE.md) | Run a command that prints a built artifact's version (`my-binary --version`) and require the output to match the release version, so a binary built from the wrong tree — or a tag that does not match the manifest — never reaches a publish step. By default the expected output is `<name> <version>` (the clap shape: the command's basename, then the version without its leading `v`); `expected` overrides it. A command that cannot run at all — missing library, crash, no such flag — fails the step even on a dry run: an artifact that does not execute is never publishable, and its exit code is never swallowed. A mismatch is a warning on a dry run, so a rehearsal reports what a real run would refuse and carries on, and a hard stop otherwise. Guide: .github/actions/RELEASE.md in megaeth-labs/.github. |
 <!-- /generated -->
diff --git a/.github/actions/RELEASE.md b/.github/actions/RELEASE.md
index 69aabe1..5d104c5 100644
--- a/.github/actions/RELEASE.md
+++ b/.github/actions/RELEASE.md
@@ -6,7 +6,8 @@ options exist, and what to do when something goes wrong.
 
 The code is next to this file: `release-candidate/`, `release-settle/`,
 `release-publish/` (the core), `release-verify-version/`,
-`release-publish-rust-crates/`, `release-upload-artifact/`, `release-assets/`
+`release-publish-rust-crates/`, `release-upload-artifact/`, `release-assets/`,
+`release-snapshot/` (the snapshot bookends)
 (the publish targets), and `release-tools/` (the text helpers they share, unit
 tested by `actions-test.yml`). The reference callers a repository stamps from
 are in `workflow-templates/` at the repository root. `README.md` beside this
@@ -313,6 +314,35 @@ and uploads `mega-evme` to the registry and the Release page;
 stateless-validator uploads both of its binaries to the registry and the
 Release page; mega-agents and salt ship nothing beyond the Release.
 
+## Snapshots (`snapshot-publish.yml`)
+
+Not every component is versioned. Deployments pin some binaries by commit —
+`version: latest`, `profile: release`, and the commit — and want "build this
+commit and push it", with no tag, no GitHub Release and no changelog. That
+is the snapshot flow: one dispatch-only workflow, `snapshot-publish.yml`,
+bookended by `release-snapshot`:
+
+1. `release-snapshot` `stage: resolve` turns the dispatch input `ref` (or
+   the run's own commit) into the full commit, refuses it unless it is
+   reachable from `allowed_branches`, and hands out the registry
+   coordinates: `version` = the commit, `path` = `<profile>/<label>`
+   (`release/latest`).
+2. The repository's own build steps, then `release-upload-artifact` per
+   file with those coordinates — the layout the tagged pipeline writes,
+   `latest` in place of the tag, so deployment tooling reads both the same
+   way. Re-runs on the same commit are no-ops for files already there.
+3. `release-snapshot` `stage: summary` writes the run summary: every
+   upload with its checksum, and the manifest entry to pin; optionally a
+   `snapshot/<package>` commit status linking back to the run.
+
+Install: copy the template, replace the build steps and destinations, and
+put the GCP secret in an environment whose deployment branch policy allows
+the branch the workflow is dispatched from (the environment authorises the
+dispatch ref; `allowed_branches` guards the commit actually built). A
+repository that also runs the tagged pipeline keeps `publish` for `v*` tags
+and gives snapshots their own environment. Nothing else is needed: no
+version file, no changelog, no rulesets, no app.
+
 ## Operations and recovery
 
 **The release branch moved after settling** (a fix landed): run settle
@@ -374,6 +404,8 @@ What each action does, in one line:
 | `release-candidate` `stage: cut` | that PR merging | creates `release-vX.Y.Z` at the merge commit |
 | `release-settle` | `workflow_dispatch` with version + tip SHA | guards, warns if the tip lacks a workflow the default branch has, regenerates the entry up to the tip and stamps the date; `direct`: commits it to the release branch and publishes at once; `pr`: opens `chore/release-settle-vX.Y.Z` (a re-run closes the previous settle PR and opens a fresh one) |
 | `release-publish` | the settle PR merging, or `release-settle` in direct mode | annotated tag at the commit (refuses if it exists or the branch drifted), GitHub Release with the entry as notes, marked latest |
+| `release-snapshot` `stage: resolve` | `workflow_dispatch` of `snapshot-publish.yml` | resolves `ref` (or the run's commit) to a full SHA, refuses it unless reachable from `allowed_branches`, outputs the registry `version` (the commit) and `path` (`<profile>/<label>`) |
+| `release-snapshot` `stage: summary` | after the uploads in the same job | run summary with every upload, its checksum and the manifest entry to pin; optional `snapshot/<package>` commit statuses |
 
 Release notes are generated from commit subjects between the previous `v*`
 tag and the settled commit, grouped by Conventional Commit type, with PR
diff --git a/.github/actions/release-snapshot/README.md b/.github/actions/release-snapshot/README.md
new file mode 100644
index 0000000..6283b91
--- /dev/null
+++ b/.github/actions/release-snapshot/README.md
@@ -0,0 +1,133 @@
+# Release · Snapshot
+
+`uses: megaeth-labs/.github/.github/actions/release-snapshot@main`
+
+<!-- generated: description -->
+The two bookends of a snapshot publish — a build of one commit pushed to the artifact registry with no tag and no GitHub Release, for components that deployments pin by commit. `stage: resolve` turns `ref` (a branch, tag or commit; empty means the run's own commit) into the coordinates the upload steps need: the full commit, and the registry `version` (the commit) and `path` (`<profile>/<label>`, e.g. `release/latest`) that match how deployment tooling addresses a snapshot. With `allowed_branches` it refuses a commit that is not reachable from one of those branches, so a dispatch cannot publish an unreviewed commit even though the environment only authorises the branch the workflow ran from. `stage: summary` writes the run summary after the uploads: where each file went, its checksum, and the manifest entry (`commit`, `version`, `profile`) a deployment repository pins; optionally it also records a commit status per package so the commit page shows what was published. Needs a checkout with history for `resolve` (the branch guard uses `merge-base`); nothing here is organisation-specific. Guide: .github/actions/RELEASE.md in megaeth-labs/.github.
+<!-- /generated -->
+
+Family: [Release pipeline](../RELEASE.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `stage` | yes |  | `resolve` (before the build) or `summary` (after the uploads). |
+| `ref` | no |  | Branch, tag or commit to publish. Empty: the run's own commit (`github.sha`). |
+| `allowed_branches` | no |  | Comma-separated branches the commit must be reachable from (`origin/<branch>` after a full checkout). Empty: no guard. |
+| `profile` | no | `release` | Build profile that names the first path segment (`release`, `profiling`, …). |
+| `label` | no | `latest` | Second path segment. Snapshots use `latest`; the deployment manifest pins the commit. |
+| `commit` | no |  | (summary) The commit that was published — the `commit` output of the resolve stage. |
+| `entries` | no |  | (summary) One line per uploaded file: `<package> <uri> <sha256> <status>`, the outputs of `release-upload-artifact` (`status` is `uploaded`, `exists` or `dry-run`). |
+| `record_status` | no | `false` | (summary) `true`: create a commit status `snapshot/<package>` on the commit for every entry, linking to this run; needs `token` with `statuses: write`. Dry runs record nothing. |
+| `token` | no | `${{ github.token }}` | (summary) Token for the commit statuses. |
+| `dry_run` | no | `false` | `true`: the summary says so and no status is recorded. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+| Output | Description |
+|---|---|
+| `commit` | (resolve) The full commit SHA that will be built. |
+| `short` | (resolve) Its 12-character prefix. |
+| `version` | (resolve) The registry version to upload under — the commit. |
+| `path` | (resolve) The registry path to upload under — `<profile>/<label>`. |
+| `describe` | (resolve) `git describe --tags --always` of the commit, for logs and binaries. |
+| `branch` | (resolve) The first of `allowed_branches` the commit was found on (empty when no guard). |
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. Resolve the commit *(only if `inputs.stage == 'resolve'`)*
+1. Write the summary *(only if `inputs.stage == 'summary'`)*
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+- `not a git checkout; check the repository out first (fetch-depth: 0)`
+- `profile must be a plain word, got`
+- `label must be a plain word, got`
+- `cannot resolve`
+- `$ref (${commit:0:12}) is not on any allowed branch ($ALLOWED); refusing to publish a commit that has not landed there`
+- `commit must be the full SHA from the resolve stage, got`
+- `entries is empty; pass one`
+- `malformed entry:`
+<!-- /generated -->
+
+## Example
+
+The two bookends of `workflow-templates/snapshot-publish.yml`; the build and
+the uploads sit between them:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0                       # the branch guard needs history
+
+- uses: megaeth-labs/.github/.github/actions/release-snapshot@main
+  id: snapshot
+  with:
+    stage: resolve
+    ref: ${{ inputs.ref }}               # empty: this run's commit
+    allowed_branches: main               # refuse anything not landed on main
+    profile: release
+
+- run: git checkout --quiet ${{ steps.snapshot.outputs.commit }}
+- run: cargo build --release -p my-binary
+
+- uses: google-github-actions/auth@v3
+  with:
+    credentials_json: ${{ secrets.GCP_AUTH_KEY }}
+
+- uses: megaeth-labs/.github/.github/actions/release-upload-artifact@main
+  id: upload
+  with:
+    file: target/release/my-binary
+    kind: artifact-registry
+    project: my-gcp-project
+    location: my-region
+    repository: my-generic-repository
+    package: my-binary
+    version: ${{ steps.snapshot.outputs.version }}   # the commit
+    path: ${{ steps.snapshot.outputs.path }}         # release/latest
+
+- uses: megaeth-labs/.github/.github/actions/release-snapshot@main
+  with:
+    stage: summary
+    commit: ${{ steps.snapshot.outputs.commit }}
+    entries: |
+      my-binary ${{ steps.upload.outputs.uri }} ${{ steps.upload.outputs.sha256 }} ${{ steps.upload.outputs.status }}
+    record_status: "true"                # needs statuses: write
+```
+
+The run summary then carries the table of uploads and the manifest entry a
+deployment repository pins:
+
+```yaml
+my-binary:
+  commit: "<full sha>"
+  version: "latest"
+  profile: "release"
+```
+
+## Notes
+
+- A snapshot is addressed by commit: the registry version *is* the commit,
+  and `<profile>/<label>` (default `release/latest`) is the path inside it —
+  the same layout the tagged pipeline writes with the tag in place of
+  `latest`. Re-running on the same commit is a no-op for files already
+  there (`release-upload-artifact` compares hashes).
+- The environment on the job authorises the ref the workflow was
+  *dispatched* on, not the commit `ref` selects; `allowed_branches` closes
+  that gap by refusing any commit not reachable from those branches.
+- `resolve` prefers `origin/<ref>` when `ref` names a branch, then anything
+  git can resolve, then a fetch of `ref` from origin.
+- No tag, no GitHub Release, no changelog. Traceability comes from the
+  environment's deployment record on the commit, the run summary, and —
+  with `record_status` — a `snapshot/<package>` commit status linking to
+  the run. A commit that must become a versioned release goes through the
+  tagged pipeline.
diff --git a/.github/actions/release-snapshot/action.yml b/.github/actions/release-snapshot/action.yml
new file mode 100644
index 0000000..96764d4
--- /dev/null
+++ b/.github/actions/release-snapshot/action.yml
@@ -0,0 +1,189 @@
+name: Release · Snapshot
+description: >-
+  The two bookends of a snapshot publish — a build of one commit pushed to
+  the artifact registry with no tag and no GitHub Release, for components
+  that deployments pin by commit. `stage: resolve` turns `ref` (a branch,
+  tag or commit; empty means the run's own commit) into the coordinates the
+  upload steps need: the full commit, and the registry `version`
+  (the commit) and `path` (`<profile>/<label>`, e.g. `release/latest`) that
+  match how deployment tooling addresses a snapshot. With `allowed_branches`
+  it refuses a commit that is not reachable from one of those branches, so a
+  dispatch cannot publish an unreviewed commit even though the environment
+  only authorises the branch the workflow ran from. `stage: summary` writes
+  the run summary after the uploads: where each file went, its checksum, and
+  the manifest entry (`commit`, `version`, `profile`) a deployment repository
+  pins; optionally it also records a commit status per package so the
+  commit page shows what was published. Needs a checkout with history for
+  `resolve` (the branch guard uses `merge-base`); nothing here is
+  organisation-specific. Guide: .github/actions/RELEASE.md in
+  megaeth-labs/.github.
+
+inputs:
+  stage:
+    description: "`resolve` (before the build) or `summary` (after the uploads)."
+    required: true
+  # --- resolve
+  ref:
+    description: "Branch, tag or commit to publish. Empty: the run's own commit (`github.sha`)."
+    required: false
+    default: ""
+  allowed_branches:
+    description: >-
+      Comma-separated branches the commit must be reachable from
+      (`origin/<branch>` after a full checkout). Empty: no guard.
+    required: false
+    default: ""
+  profile:
+    description: "Build profile that names the first path segment (`release`, `profiling`, …)."
+    required: false
+    default: release
+  label:
+    description: "Second path segment. Snapshots use `latest`; the deployment manifest pins the commit."
+    required: false
+    default: latest
+  # --- summary
+  commit:
+    description: "(summary) The commit that was published — the `commit` output of the resolve stage."
+    required: false
+    default: ""
+  entries:
+    description: >-
+      (summary) One line per uploaded file: `<package> <uri> <sha256> <status>`,
+      the outputs of `release-upload-artifact` (`status` is `uploaded`,
+      `exists` or `dry-run`).
+    required: false
+    default: ""
+  record_status:
+    description: >-
+      (summary) `true`: create a commit status `snapshot/<package>` on the
+      commit for every entry, linking to this run; needs `token` with
+      `statuses: write`. Dry runs record nothing.
+    required: false
+    default: "false"
+  token:
+    description: "(summary) Token for the commit statuses."
+    required: false
+    default: ${{ github.token }}
+  dry_run:
+    description: "`true`: the summary says so and no status is recorded."
+    required: false
+    default: "false"
+
+outputs:
+  commit:
+    description: (resolve) The full commit SHA that will be built.
+    value: ${{ steps.resolve.outputs.commit }}
+  short:
+    description: (resolve) Its 12-character prefix.
+    value: ${{ steps.resolve.outputs.short }}
+  version:
+    description: (resolve) The registry version to upload under — the commit.
+    value: ${{ steps.resolve.outputs.commit }}
+  path:
+    description: (resolve) The registry path to upload under — `<profile>/<label>`.
+    value: ${{ steps.resolve.outputs.path }}
+  describe:
+    description: (resolve) `git describe --tags --always` of the commit, for logs and binaries.
+    value: ${{ steps.resolve.outputs.describe }}
+  branch:
+    description: (resolve) The first of `allowed_branches` the commit was found on (empty when no guard).
+    value: ${{ steps.resolve.outputs.branch }}
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve the commit
+      id: resolve
+      if: inputs.stage == 'resolve'
+      shell: bash
+      env:
+        REF: ${{ inputs.ref }}
+        ALLOWED: ${{ inputs.allowed_branches }}
+        PROFILE: ${{ inputs.profile }}
+        LABEL: ${{ inputs.label }}
+        RUN_SHA: ${{ github.sha }}
+      run: |
+        set -euo pipefail
+        git rev-parse --git-dir >/dev/null 2>&1 || { echo "::error::not a git checkout; check the repository out first (fetch-depth: 0)"; exit 1; }
+        [[ "$PROFILE" =~ ^[A-Za-z0-9._-]+$ ]] || { echo "::error::profile must be a plain word, got '$PROFILE'"; exit 1; }
+        [[ "$LABEL" =~ ^[A-Za-z0-9._-]+$ ]] || { echo "::error::label must be a plain word, got '$LABEL'"; exit 1; }
+        ref="${REF:-$RUN_SHA}"
+        # Prefer the remote branch of that name (a dispatch may name a branch
+        # the shallow checkout never created locally), then anything git can
+        # resolve.
+        if git rev-parse --verify --quiet "refs/remotes/origin/$ref^{commit}" >/dev/null; then
+          commit="$(git rev-parse "refs/remotes/origin/$ref^{commit}")"
+        elif git rev-parse --verify --quiet "$ref^{commit}" >/dev/null; then
+          commit="$(git rev-parse "$ref^{commit}")"
+        else
+          git fetch --quiet origin "$ref" 2>/dev/null && commit="$(git rev-parse FETCH_HEAD)" \
+            || { echo "::error::cannot resolve '$ref' to a commit in this checkout"; exit 1; }
+        fi
+        found=""
+        if [[ -n "$ALLOWED" ]]; then
+          IFS=',' read -ra branches <<<"$ALLOWED"
+          for b in "${branches[@]}"; do
+            b="${b// /}"; [[ -n "$b" ]] || continue
+            git rev-parse --verify --quiet "refs/remotes/origin/$b" >/dev/null || git fetch --quiet origin "$b:refs/remotes/origin/$b" 2>/dev/null || true
+            git rev-parse --verify --quiet "refs/remotes/origin/$b" >/dev/null || { echo "::warning::allowed branch '$b' does not exist on origin"; continue; }
+            if git merge-base --is-ancestor "$commit" "refs/remotes/origin/$b"; then found="$b"; break; fi
+          done
+          [[ -n "$found" ]] || { echo "::error::$ref (${commit:0:12}) is not on any allowed branch ($ALLOWED); refusing to publish a commit that has not landed there"; exit 1; }
+        fi
+        describe="$(git describe --tags --always "$commit" 2>/dev/null || echo "${commit:0:12}")"
+        {
+          echo "commit=$commit"; echo "short=${commit:0:12}"; echo "path=${PROFILE}/${LABEL}"
+          echo "describe=$describe"; echo "branch=$found"
+        } >> "$GITHUB_OUTPUT"
+        echo "snapshot of $ref = $commit ($describe)${found:+, on $found}; registry version $commit, path ${PROFILE}/${LABEL}"
+
+    - name: Write the summary
+      id: summary
+      if: inputs.stage == 'summary'
+      shell: bash
+      env:
+        COMMIT: ${{ inputs.commit }}
+        ENTRIES: ${{ inputs.entries }}
+        PROFILE: ${{ inputs.profile }}
+        LABEL: ${{ inputs.label }}
+        RECORD: ${{ inputs.record_status }}
+        GH_TOKEN: ${{ inputs.token }}
+        DRY_RUN: ${{ inputs.dry_run }}
+        REPO: ${{ github.repository }}
+        RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+      run: |
+        set -euo pipefail
+        [[ "$COMMIT" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::commit must be the full SHA from the resolve stage, got '$COMMIT'"; exit 1; }
+        [[ -n "$ENTRIES" ]] || { echo "::error::entries is empty; pass one '<package> <uri> <sha256> <status>' line per uploaded file"; exit 1; }
+        {
+          if [[ "$DRY_RUN" == "true" ]]; then echo "## Snapshot rehearsal of \`${COMMIT:0:12}\` (nothing uploaded)"; else echo "## Snapshot \`${COMMIT:0:12}\` published"; fi
+          echo
+          echo "| Package | Destination | SHA256 | Status |"
+          echo "|---|---|---|---|"
+        } >> "$GITHUB_STEP_SUMMARY"
+        packages=()
+        while IFS= read -r line; do
+          [[ -n "${line// /}" ]] || continue
+          read -r package uri sha status <<<"$line"
+          [[ -n "$package" && -n "$uri" && -n "$sha" && -n "$status" ]] || { echo "::error::malformed entry: '$line'"; exit 1; }
+          echo "| \`$package\` | $uri | \`$sha\` | $status |" >> "$GITHUB_STEP_SUMMARY"
+          packages+=("$package")
+          if [[ "$RECORD" == "true" && "$DRY_RUN" != "true" ]]; then
+            gh api --method POST "repos/$REPO/statuses/$COMMIT" \
+              -f state=success -f context="snapshot/$package" -f target_url="$RUN_URL" \
+              -f description="${status}: ${uri:0:100}" >/dev/null \
+              && echo "recorded status snapshot/$package on ${COMMIT:0:12}" \
+              || echo "::warning::could not record status snapshot/$package (does the token have statuses: write?)"
+          fi
+        done <<<"$ENTRIES"
+        {
+          echo
+          echo "Deployment manifest entry (the registry path is \`${PROFILE}/${LABEL}\` under version \`${COMMIT}\`):"
+          echo
+          echo '```yaml'
+          for package in "${packages[@]}"; do
+            echo "$package:"; echo "  commit: \"$COMMIT\""; echo "  version: \"$LABEL\""; echo "  profile: \"$PROFILE\""
+          done
+          echo '```'
+        } >> "$GITHUB_STEP_SUMMARY"
+        echo "summary written for ${#packages[@]} package(s)"
diff --git a/.github/workflows/actions-test.yml b/.github/workflows/actions-test.yml
index 9760074..ce67717 100644
--- a/.github/workflows/actions-test.yml
+++ b/.github/workflows/actions-test.yml
@@ -110,6 +110,80 @@ jobs:
           [[ "$BROKEN" == "failure" ]] || { echo "a broken probe should fail on a dry run too, got $BROKEN"; exit 1; }
           echo "all outcomes as documented"
 
+  # release-snapshot: resolve a ref with and without the branch guard, refuse
+  # a commit that is not on an allowed branch, and write the summary.
+  snapshot:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve main, guarded by main
+        id: main
+        uses: ./.github/actions/release-snapshot
+        with:
+          stage: resolve
+          ref: main
+          allowed_branches: main
+
+      - name: Resolve the run's own commit, no guard, profiling
+        id: own
+        uses: ./.github/actions/release-snapshot
+        with:
+          stage: resolve
+          profile: profiling
+
+      - name: A commit off every allowed branch is refused
+        id: refused
+        continue-on-error: true
+        uses: ./.github/actions/release-snapshot
+        with:
+          stage: resolve
+          allowed_branches: no-such-branch
+
+      - name: Check the coordinates
+        env:
+          MAIN_COMMIT: ${{ steps.main.outputs.commit }}
+          MAIN_BRANCH: ${{ steps.main.outputs.branch }}
+          MAIN_PATH: ${{ steps.main.outputs.path }}
+          OWN_COMMIT: ${{ steps.own.outputs.commit }}
+          OWN_VERSION: ${{ steps.own.outputs.version }}
+          OWN_PATH: ${{ steps.own.outputs.path }}
+          REFUSED: ${{ steps.refused.outcome }}
+        run: |
+          set -euo pipefail
+          [[ "$MAIN_COMMIT" == "$(git rev-parse origin/main)" ]] || { echo "main resolved to $MAIN_COMMIT"; exit 1; }
+          [[ "$MAIN_BRANCH" == "main" && "$MAIN_PATH" == "release/latest" ]] || { echo "branch=$MAIN_BRANCH path=$MAIN_PATH"; exit 1; }
+          [[ "$OWN_COMMIT" == "$GITHUB_SHA" && "$OWN_VERSION" == "$GITHUB_SHA" ]] || { echo "own commit=$OWN_COMMIT version=$OWN_VERSION"; exit 1; }
+          [[ "$OWN_PATH" == "profiling/latest" ]] || { echo "own path=$OWN_PATH"; exit 1; }
+          [[ "$REFUSED" == "failure" ]] || { echo "an off-branch commit should be refused, got $REFUSED"; exit 1; }
+          echo "coordinates as documented"
+
+      - name: Summary of a rehearsal
+        uses: ./.github/actions/release-snapshot
+        with:
+          stage: summary
+          commit: ${{ steps.own.outputs.commit }}
+          profile: profiling
+          entries: |
+            my-binary https://example.invalid/my-binary 0123abcd dry-run
+            my-tool https://example.invalid/my-tool 4567ef01 dry-run
+          dry_run: "true"
+
+      - name: Check the summary
+        run: |
+          set -euo pipefail
+          grep -q 'Snapshot rehearsal of' "$GITHUB_STEP_SUMMARY"
+          grep -q '| `my-tool` | https://example.invalid/my-tool | `4567ef01` | dry-run |' "$GITHUB_STEP_SUMMARY"
+          grep -q '^my-binary:$' "$GITHUB_STEP_SUMMARY"
+          grep -q "  commit: \"$GITHUB_SHA\"" "$GITHUB_STEP_SUMMARY"
+          grep -q '  profile: "profiling"' "$GITHUB_STEP_SUMMARY"
+          echo "summary carries the manifest entry"
+
   # The generated parts of every action README (inputs, outputs, steps,
   # errors) and the catalogue come from action.yml; stale docs fail here.
   docs:
diff --git a/workflow-templates/snapshot-publish.properties.json b/workflow-templates/snapshot-publish.properties.json
new file mode 100644
index 0000000..b9367c5
--- /dev/null
+++ b/workflow-templates/snapshot-publish.properties.json
@@ -0,0 +1,8 @@
+{
+  "name": "Snapshot Publish",
+  "description": "Build one commit and push it to the MegaETH artifact registry with no tag and no GitHub Release, for components deployments pin by commit. Dispatch with dry_run to rehearse.",
+  "iconName": "octicon package",
+  "categories": [
+    "Automation"
+  ]
+}
diff --git a/workflow-templates/snapshot-publish.yml b/workflow-templates/snapshot-publish.yml
new file mode 100644
index 0000000..2315612
--- /dev/null
+++ b/workflow-templates/snapshot-publish.yml
@@ -0,0 +1,119 @@
+name: Snapshot Publish
+
+# Build one commit and push its binaries to the artifact registry, with no
+# tag and no GitHub Release: the snapshot flow for components that
+# deployments pin by commit (`version: latest`, `profile: <profile>` in the
+# deployment manifest, next to the commit). Dispatch only:
+#   gh workflow run snapshot-publish.yml --ref main                 # head of main
+#   gh workflow run snapshot-publish.yml --ref main -f ref=<sha>    # an older commit on main
+#   … -f dry_run=true                                               # rehearse: build, upload nothing
+#
+# What gets built is `ref` if given, else the run's own commit. The `publish`
+# environment authorises the *dispatch* ref (the branch the workflow ran
+# from), so its deployment branch policy must list that branch; the
+# `allowed_branches` guard below is what stops a dispatch from publishing a
+# commit that never landed on it. A repository that also runs the tagged
+# release pipeline can keep `publish` for tags only and give snapshots their
+# own environment (`snapshot`, same GCP secret, branch policy `main`).
+#
+# The registry layout is what the tagged pipeline produces, with `latest` in
+# place of the tag: `<package>/<commit>/<profile>/latest/<file>`. A rerun on
+# the same commit is a no-op for files already there (hash-checked) and a
+# failure if the file changed, never a silent overwrite.
+#
+# Every destination below is a placeholder — there are no defaults.
+# Guide: https://github.com/megaeth-labs/.github/blob/main/.github/actions/RELEASE.md
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Commit or branch to build (empty: the commit this workflow runs on)"
+        required: false
+        type: string
+        default: ""
+      profile:
+        description: "Build profile; first segment of the registry path"
+        required: false
+        type: choice
+        options: [release]
+        default: release
+      dry_run:
+        description: "Build and check everything; upload nothing"
+        required: false
+        type: boolean
+        default: true
+
+# One run per commit-to-build; never cancel an upload mid-flight.
+concurrency:
+  group: ${{ github.workflow }}-${{ inputs.ref || github.sha }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  DRY_RUN: ${{ inputs.dry_run }}
+
+jobs:
+  binary:
+    runs-on: ubuntu-latest
+    environment: publish
+    permissions:
+      contents: read
+      statuses: write # release-snapshot record_status; drop with it
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: megaeth-labs/.github/.github/actions/release-snapshot@main
+        id: snapshot
+        with:
+          stage: resolve
+          ref: ${{ inputs.ref }}
+          allowed_branches: main
+          profile: ${{ inputs.profile }}
+
+      - name: Check out the commit to build
+        if: steps.snapshot.outputs.commit != github.sha
+        run: git checkout --quiet ${{ steps.snapshot.outputs.commit }}
+
+      - uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
+        with:
+          cache: false
+
+      - name: Build
+        run: cargo build --release --locked -p my-binary
+
+      # No version to verify against; just make sure the artifact runs.
+      - name: Smoke-test the binary
+        run: target/release/my-binary --version
+
+      - uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3
+        with:
+          credentials_json: ${{ secrets.GCP_AUTH_KEY }}
+
+      - uses: megaeth-labs/.github/.github/actions/release-upload-artifact@main
+        id: upload
+        with:
+          file: target/release/my-binary
+          kind: artifact-registry
+          project: my-gcp-project
+          location: my-region
+          repository: my-generic-repository
+          package: my-binary
+          version: ${{ steps.snapshot.outputs.version }}
+          path: ${{ steps.snapshot.outputs.path }}
+          dry_run: ${{ env.DRY_RUN }}
+
+      - uses: megaeth-labs/.github/.github/actions/release-snapshot@main
+        with:
+          stage: summary
+          commit: ${{ steps.snapshot.outputs.commit }}
+          profile: ${{ inputs.profile }}
+          entries: |
+            my-binary ${{ steps.upload.outputs.uri }} ${{ steps.upload.outputs.sha256 }} ${{ steps.upload.outputs.status }}
+          record_status: "true"
+          dry_run: ${{ env.DRY_RUN }}

From f9ffbf03e0fe23e4b2c86af1049de829f22ace90 Mon Sep 17 00:00:00 2001
From: William Aaron Cheung <git@troublor.xyz>
Date: Thu, 10 Sep 2026 16:47:51 +0800
Subject: [PATCH 2/2] feat(release-snapshot): expose the manifest and package
 list as outputs

A later step cannot read GITHUB_STEP_SUMMARY (it is per step), so the
summary stage now also outputs the manifest text and the package list;
the test checks those.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .github/actions/release-snapshot/README.md  |  2 ++
 .github/actions/release-snapshot/action.yml | 18 +++++++++++++++---
 .github/workflows/actions-test.yml          | 18 +++++++++++-------
 3 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/.github/actions/release-snapshot/README.md b/.github/actions/release-snapshot/README.md
index 6283b91..b9776f3 100644
--- a/.github/actions/release-snapshot/README.md
+++ b/.github/actions/release-snapshot/README.md
@@ -36,6 +36,8 @@ Family: [Release pipeline](../RELEASE.md).
 | `path` | (resolve) The registry path to upload under — `<profile>/<label>`. |
 | `describe` | (resolve) `git describe --tags --always` of the commit, for logs and binaries. |
 | `branch` | (resolve) The first of `allowed_branches` the commit was found on (empty when no guard). |
+| `packages` | (summary) Comma-separated package names from `entries`. |
+| `manifest` | (summary) The manifest entries as YAML text, `<package>` → `commit`, `version`, `profile` per package, for a follow-up that pins them somewhere. |
 <!-- /generated -->
 
 ## What it runs
diff --git a/.github/actions/release-snapshot/action.yml b/.github/actions/release-snapshot/action.yml
index 96764d4..25301d0 100644
--- a/.github/actions/release-snapshot/action.yml
+++ b/.github/actions/release-snapshot/action.yml
@@ -88,6 +88,12 @@ outputs:
   branch:
     description: (resolve) The first of `allowed_branches` the commit was found on (empty when no guard).
     value: ${{ steps.resolve.outputs.branch }}
+  packages:
+    description: (summary) Comma-separated package names from `entries`.
+    value: ${{ steps.summary.outputs.packages }}
+  manifest:
+    description: "(summary) The manifest entries as YAML text, `<package>` → `commit`, `version`, `profile` per package, for a follow-up that pins them somewhere."
+    value: ${{ steps.summary.outputs.manifest }}
 
 runs:
   using: composite
@@ -176,14 +182,20 @@ runs:
               || echo "::warning::could not record status snapshot/$package (does the token have statuses: write?)"
           fi
         done <<<"$ENTRIES"
+        manifest=""
+        for package in "${packages[@]}"; do
+          manifest+="$package:"$'\n'"  commit: \"$COMMIT\""$'\n'"  version: \"$LABEL\""$'\n'"  profile: \"$PROFILE\""$'\n'
+        done
         {
           echo
           echo "Deployment manifest entry (the registry path is \`${PROFILE}/${LABEL}\` under version \`${COMMIT}\`):"
           echo
           echo '```yaml'
-          for package in "${packages[@]}"; do
-            echo "$package:"; echo "  commit: \"$COMMIT\""; echo "  version: \"$LABEL\""; echo "  profile: \"$PROFILE\""
-          done
+          printf '%s' "$manifest"
           echo '```'
         } >> "$GITHUB_STEP_SUMMARY"
+        {
+          echo "packages=$(IFS=,; echo "${packages[*]}")"
+          echo "manifest<<megaeth_release_snapshot"; printf '%s' "$manifest"; echo "megaeth_release_snapshot"
+        } >> "$GITHUB_OUTPUT"
         echo "summary written for ${#packages[@]} package(s)"
diff --git a/.github/workflows/actions-test.yml b/.github/workflows/actions-test.yml
index ce67717..b6fea76 100644
--- a/.github/workflows/actions-test.yml
+++ b/.github/workflows/actions-test.yml
@@ -164,6 +164,7 @@ jobs:
           echo "coordinates as documented"
 
       - name: Summary of a rehearsal
+        id: summary
         uses: ./.github/actions/release-snapshot
         with:
           stage: summary
@@ -174,15 +175,18 @@ jobs:
             my-tool https://example.invalid/my-tool 4567ef01 dry-run
           dry_run: "true"
 
-      - name: Check the summary
+      # GITHUB_STEP_SUMMARY is a per-step file, so the summary itself cannot be
+      # read back here; the manifest output carries the same entries.
+      - name: Check the manifest output
+        env:
+          PACKAGES: ${{ steps.summary.outputs.packages }}
+          MANIFEST: ${{ steps.summary.outputs.manifest }}
         run: |
           set -euo pipefail
-          grep -q 'Snapshot rehearsal of' "$GITHUB_STEP_SUMMARY"
-          grep -q '| `my-tool` | https://example.invalid/my-tool | `4567ef01` | dry-run |' "$GITHUB_STEP_SUMMARY"
-          grep -q '^my-binary:$' "$GITHUB_STEP_SUMMARY"
-          grep -q "  commit: \"$GITHUB_SHA\"" "$GITHUB_STEP_SUMMARY"
-          grep -q '  profile: "profiling"' "$GITHUB_STEP_SUMMARY"
-          echo "summary carries the manifest entry"
+          [[ "$PACKAGES" == "my-binary,my-tool" ]] || { echo "packages=$PACKAGES"; exit 1; }
+          expected="$(printf 'my-binary:\n  commit: "%s"\n  version: "latest"\n  profile: "profiling"\nmy-tool:\n  commit: "%s"\n  version: "latest"\n  profile: "profiling"\n' "$GITHUB_SHA" "$GITHUB_SHA")"
+          [[ "$MANIFEST" == "$expected" ]] || { echo "manifest differs:"; diff <(echo "$expected") <(echo "$MANIFEST") || true; exit 1; }
+          echo "manifest entries as documented"
 
   # The generated parts of every action README (inputs, outputs, steps,
   # errors) and the catalogue come from action.yml; stale docs fail here.