Model deploy pins as a rolling candidate + frozen releases (audited 0_1_1 preserved)

.github/workflows/package-release.yaml

@@ -1,37 +1,30 @@
 name: Package Release
 on:
   push:
-    branches:
-      - main
+    tags:
+      - sol-v*
 jobs:
   release:
-    # rainix-autopublish's job requests contents: write (to push the version-
-    # bump commit + tag) and id-token: write. This repo's default workflow-token
-    # permission is read-only, so without granting these here the reusable's
-    # request exceeds the caller and the run fails at startup. Grant exactly the
-    # scopes the reusable needs, per workflow, rather than flipping the whole
-    # repo default to write.
+    # rainix-tag-release verifies the tag, publishes to soldeer, freezes the
+    # candidate snapshot into a numbered release dir, and commits it back — so it
+    # needs contents: write (push the release commit) and id-token: write. This
+    # repo's default workflow-token permission is read-only, so grant exactly
+    # those scopes here or the reusable's request exceeds the caller and the run
+    # fails at startup.
     permissions:
       contents: write
       id-token: write
-    uses: rainlanguage/rainix/.github/workflows/rainix-autopublish.yaml@main
+    # A DEPLOY repo is on the tag-release lifecycle, not autopublish. A release
+    # is cut by pushing a `sol-vX.Y.Z` tag (never on merge); deployment is a
+    # separate manual step. `[package].version` is the LAST released version and
+    # moves only at release, in lockstep with the frozen snapshot the tag cuts.
+    # This is the counterpart to library repos, which use rainix-autopublish and
+    # bump a next-version slot on every merge. Mirrors the rain.factory.deploy
+    # caller. `cut-release.sh` freezes `src/generated/candidate/` into
+    # `src/generated/<version>/` (see the script) then regenerates the libs.
+    uses: rainlanguage/rainix/.github/workflows/rainix-tag-release.yaml@main
     with:
-      # `foundry.toml` version is the NEXT (in-development) release (see #244). On
-      # merge, publish that version and bump to the next — the bump no longer
-      # generates artifacts (rainix#267). A version's deploy-pin snapshot is built
-      # by the PR that changes the bytecode: run
-      # `forge script ./script/BuildPointers.sol` (after `forge soldeer install`)
-      # and commit the new `src/generated/<tag>/` snapshot + regenerated deploy
-      # libs. The LibProdDeploy fork/deploy tests fail if a snapshot is stale, and
-      # the rainix append-only check (rainix#268) rejects any change to a snapshot
-      # already on main, so snapshots stay frozen once merged.
       soldeer-package: st0x-deploy
-    # Secrets are passed explicitly (not `inherit`), mirroring this repo's other
-    # cross-org rainix callers (e.g. rainix-sol.yaml). Only SOLDEER_API_TOKEN is
-    # required for the publish; the rest are optional and fall back cleanly when
-    # empty (bot git identity; GITHUB_TOKEN push, since main is unprotected).
-    secrets:
-      SOLDEER_API_TOKEN: ${{ secrets.SOLDEER_API_TOKEN }}
-      PUBLISH_PRIVATE_KEY: ${{ secrets.PUBLISH_PRIVATE_KEY }}
-      CI_GIT_EMAIL: ${{ secrets.CI_GIT_EMAIL }}
-      CI_GIT_USER: ${{ secrets.CI_GIT_USER }}
+      tag-prefix: sol-v
+      snapshot-generate-cmd: bash script/cut-release.sh
+    secrets: inherit

foundry.toml

@@ -5,7 +5,7 @@
 # clean. So this holds the next unpublished version, not the last published one.
 [package]
 name = "st0x-deploy"
-version = "0.1.30"
+version = "0.1.1"
 
 [profile.default]
 libs = ['dependencies']

script/BuildPointers.sol

@@ -29,19 +29,26 @@ import {ST0xOrchestrator} from "../src/concrete/ST0xOrchestrator.sol";
 import {ST0xOrchestratorBeaconSetDeployer} from "../src/concrete/deploy/ST0xOrchestratorBeaconSetDeployer.sol";
 
 contract BuildPointers is Script {
-    /// @notice The canonical release tag. Read from `foundry.toml`
-    /// `[package].version` — the single source of truth — with dots converted
-    /// to underscores for the Solidity constant/dir form (`0.1.3` -> `0_1_3`).
-    /// Everything version-dependent (the `<tag>/` snapshot dir, `DEPLOY_TAG`,
-    /// the current-release aliases) derives from this.
-    function deployTag() internal view returns (string memory) {
-        string memory version = vm.parseTomlString(vm.readFile("foundry.toml"), ".package.version");
-        bytes memory b = bytes(version);
-        bytes memory out = new bytes(b.length);
-        for (uint256 i = 0; i < b.length; i++) {
-            out[i] = b[i] == "." ? bytes1("_") : b[i];
-        }
-        return string(out);
+    /// @notice The rolling "current source" snapshot tag — always `candidate`,
+    /// never a version number. `src/generated/candidate/` is regenerated from
+    /// the current source on every run; a numbered snapshot is frozen only when
+    /// a release tag promotes `candidate` (see `script/cut-release.sh`). Source
+    /// self-references (`LibProdDeployCurrent`) always resolve to `candidate`,
+    /// so they track whatever the source currently compiles to, while numbered
+    /// snapshots (`0_1_1`, …) stay frozen and are never regenerated here.
+    string constant CANDIDATE_TAG = "candidate";
+
+    function deployTag() internal pure returns (string memory) {
+        return CANDIDATE_TAG;
+    }
+
+    /// @notice The constant-name suffix for a tag dir. Numbered tags use the tag
+    /// verbatim (`0_1_1`); the rolling `candidate` dir uses `CANDIDATE`, so its
+    /// generated constants read `STOX_RECEIPT_CANDIDATE` rather than the
+    /// lowercase dir name.
+    function tagSuffix(string memory tag) internal pure returns (string memory) {
+        if (keccak256(bytes(tag)) == keccak256(bytes(CANDIDATE_TAG))) return "CANDIDATE";
+        return tag;
     }
 
     function addressConstantString(address addr) internal pure returns (string memory) {
@@ -88,8 +95,8 @@ contract BuildPointers is Script {
     function run() external {
         LibRainDeploy.etchZoltuFactory(vm);
 
-        // A fresh next-version slot has no `<tag>/` dir yet, and `vm.writeFile`
-        // won't create one.
+        // Regenerate the rolling `candidate/` snapshot from current source.
+        // `vm.writeFile` won't create the dir, so ensure it exists first.
         vm.createDir(string.concat("src/generated/", deployTag()), true);
 
         buildContractPointers("StoxCorporateActionsFacet", type(StoxCorporateActionsFacet).creationCode);
@@ -215,7 +222,10 @@ contract BuildPointers is Script {
     }
 
     /// @notice A monotonic sort key for an `a_b_c` tag (each component < 1e6).
+    /// The non-numeric `candidate` tag sorts last (the rolling head after every
+    /// frozen numbered release).
     function tagKey(string memory name) internal pure returns (uint256 key) {
+        if (keccak256(bytes(name)) == keccak256(bytes(CANDIDATE_TAG))) return type(uint256).max;
         bytes memory b = bytes(name);
         uint256 num = 0;
         for (uint256 i = 0; i < b.length; i++) {
@@ -239,7 +249,7 @@ contract BuildPointers is Script {
         for (uint256 i = 0; i < entries.length; i++) {
             if (!entries[i].isDir) continue;
             string memory name = baseName(entries[i].path);
-            if (isTagName(name)) {
+            if (isTagName(name) || keccak256(bytes(name)) == keccak256(bytes(CANDIDATE_TAG))) {
                 tmp[n] = name;
                 n++;
             }
@@ -278,31 +288,36 @@ contract BuildPointers is Script {
         pure
         returns (string memory)
     {
+        string memory suffix = tagSuffix(tag);
         string memory head =
-            string.concat("import {DEPLOYED_ADDRESS as ", base, "_ADDRESS_", tag, "_GEN, BYTECODE_HASH as ", base);
+            string.concat("import {DEPLOYED_ADDRESS as ", base, "_ADDRESS_", suffix, "_GEN, BYTECODE_HASH as ", base);
         string memory mid = string.concat(
-            "_CODEHASH_", tag, "_GEN, CREATION_CODE as ", base, "_CREATION_", tag, "_GEN, RUNTIME_CODE as ", base
+            "_CODEHASH_", suffix, "_GEN, CREATION_CODE as ", base, "_CREATION_", suffix, "_GEN, RUNTIME_CODE as ", base
         );
-        string memory tail = string.concat("_RUNTIME_", tag, '_GEN} from "./', tag, "/", name, '.pointers.sol";');
+        string memory tail = string.concat("_RUNTIME_", suffix, '_GEN} from "./', tag, "/", name, '.pointers.sol";');
         return string.concat(head, mid, tail);
     }
 
     /// @notice Emit the four aliased constants for one (tag, contract).
     function emitV4Constants(string memory tag, string memory base) internal {
+        string memory suffix = tagSuffix(tag);
         vm.writeLine(
-            GEN_V4_PATH, string.concat("address constant ", base, "_", tag, " = ", base, "_ADDRESS_", tag, "_GEN;")
+            GEN_V4_PATH,
+            string.concat("address constant ", base, "_", suffix, " = ", base, "_ADDRESS_", suffix, "_GEN;")
         );
         vm.writeLine(
             GEN_V4_PATH,
-            string.concat("bytes32 constant ", base, "_CODEHASH_", tag, " = ", base, "_CODEHASH_", tag, "_GEN;")
+            string.concat("bytes32 constant ", base, "_CODEHASH_", suffix, " = ", base, "_CODEHASH_", suffix, "_GEN;")
         );
         vm.writeLine(
             GEN_V4_PATH,
-            string.concat("bytes constant ", base, "_CREATION_CODE_", tag, " = ", base, "_CREATION_", tag, "_GEN;")
+            string.concat(
+                "bytes constant ", base, "_CREATION_CODE_", suffix, " = ", base, "_CREATION_", suffix, "_GEN;"
+            )
         );
         vm.writeLine(
             GEN_V4_PATH,
-            string.concat("bytes constant ", base, "_RUNTIME_CODE_", tag, " = ", base, "_RUNTIME_", tag, "_GEN;")
+            string.concat("bytes constant ", base, "_RUNTIME_CODE_", suffix, " = ", base, "_RUNTIME_", suffix, "_GEN;")
         );
     }
 
@@ -357,6 +372,7 @@ contract BuildPointers is Script {
     /// current release tag.
     function genCurrent() internal {
         string memory tag = deployTag();
+        string memory suffix = tagSuffix(tag);
         require(vm.exists(string.concat("src/generated/", tag)), "BuildPointers: current tag dir missing");
         string[12] memory names = contractNames();
         string[12] memory bases = contractBases();
@@ -379,11 +395,14 @@ contract BuildPointers is Script {
             if (!pointerExists(tag, names[c])) continue;
             string memory base = bases[c];
             vm.writeLine(
-                GEN_CURRENT_PATH, string.concat("address constant ", base, " = LibProdDeployV4.", base, "_", tag, ";")
+                GEN_CURRENT_PATH,
+                string.concat("address constant ", base, " = LibProdDeployV4.", base, "_", suffix, ";")
             );
             vm.writeLine(
                 GEN_CURRENT_PATH,
-                string.concat("bytes32 constant ", base, "_CODEHASH = LibProdDeployV4.", base, "_CODEHASH_", tag, ";")
+                string.concat(
+                    "bytes32 constant ", base, "_CODEHASH = LibProdDeployV4.", base, "_CODEHASH_", suffix, ";"
+                )
             );
         }
         vm.writeLine(GEN_CURRENT_PATH, "}");