objectstack-ai
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 158 additions & 25 deletions b/‎.github/workflows/release.yml‎
Lines changed: 158 additions & 25 deletions
@@ -40,14 +40,15 @@ name: Release
 #
 # HOW THE LANES ARE SPLIT NOW
 # ---------------------------
-#   push to main  →  `version-pr`         keeps the "chore: version packages" PR
-#                                          (#4935) current. Carries NO publish
-#                                          capability: the changesets step is
+#   schedule (6-hourly)  →  `version-pr`  keeps the "chore: version packages" PR
+#   or a dispatch with                     (#4935) current. Carries NO publish
+#   `refresh_version_pr`                   capability: the changesets step is
 #                                          invoked WITHOUT a `publish:` script,
 #                                          so the action's publish branch is
 #                                          unreachable by construction, not by
 #                                          an `if:` someone can get wrong.
-#                 →  `release-integrity`   audits ONLY the version at
+#                                          NOT on push — see the section below.
+#   push to main  →  `release-integrity`   audits ONLY the version at
 #                                          `github.sha`. Never publishes, never
 #                                          pushes a tag. May backfill GitHub
 #                                          Releases / the ADR-0087 D4 asset /
@@ -64,8 +65,58 @@ name: Release
 #                                          at `environment: release` until a
 #                                          required reviewer approves it.
 #   workflow_dispatch → `publish`          the repair lane. Takes no version;
-#                                          audits main exactly as the push lane
-#                                          does. Same environment gate.
+#   (WITHOUT                                audits main exactly as the push lane
+#    `refresh_version_pr`)                  does. Same environment gate.
+#
+# WHY `version-pr` LEFT THE PUSH TRIGGER (#11233, 2026-08-23)
+# ----------------------------------------------------------
+# changesets/action's version path is `git reset --hard <github.context.sha>` →
+# re-version → `git push --force origin HEAD:changeset-release/main` (its source
+# is quoted at the top of this file). On push that recomputes and force-pushes
+# #4935 on EVERY landing, and main takes ~18 merges a working day. The standing
+# Version Packages PR therefore never held still long enough for its own branch
+# CI to finish: every run was superseded by the next force-push, so the PR could
+# not converge and was ejected from the merge queue on entry. That is a
+# structural property of (action algorithm × trigger frequency), not of the CLI
+# version — this repo is already on @changesets/cli ^3.0.0 and the churn was
+# unchanged. The fix is the one the changesets project documents for exactly
+# this: refresh on a SCHEDULE instead of on every push.
+#
+# Between refreshes `changeset-release/main` is a static branch. Its CI
+# converges, and it merges through the ordinary queue like any other PR. A stale
+# window of up to six hours is the whole cost, and it is bounded on demand:
+# dispatch with `refresh_version_pr` when you want it current NOW (immediately
+# before a GA cut, say). The bookkeeping is not time-critical — the changesets
+# are already committed on main; #4935 is only their rendering.
+#
+# ⛔ THE DISPATCH COLLISION, AND WHY THERE IS AN INPUT FOR IT
+# ----------------------------------------------------------
+# `workflow_dispatch` was already taken: it is the publish REPAIR lane (D4).
+# One event name now has to start two lanes that must never start each other —
+# a refresh that also queued the publish audit would park a WAITING DEPLOYMENT
+# at the `release` environment on every routine refresh, i.e. an approval prompt
+# a maintainer must open and dismiss to keep the real ones meaningful. Approval
+# noise is how an approval stops being read, and this file's whole barrier is
+# that approval (see below).
+#
+# So the event is split by an INPUT rather than by a second workflow file (the
+# maintainer does not want another lane to maintain, and a second file would
+# duplicate the publish invariants where they can drift apart):
+#
+#     dispatch WITH    `refresh_version_pr` → version-pr only, no deployment
+#     dispatch WITHOUT `refresh_version_pr` → the repair lane, exactly as before
+#     schedule                              → version-pr only
+#     push to main                          → release-integrity (+ publish)
+#
+# Every job carries the half of that split it needs, in its own `if:`. No job
+# infers its lane from another job's presence.
+#
+# ⚠️ The two inputs are INDEPENDENT, so `refresh_version_pr` + `force` is a
+# reachable form, and it is refused rather than resolved: `publish`'s guard
+# excludes any dispatch carrying `refresh_version_pr`, so that combination
+# refreshes and publishes NOTHING. A dispatch that both refreshes bookkeeping
+# and force-publishes is not a thing anyone means; the harmless reading is the
+# one that runs.
 #
 # WHERE THE HUMAN IS, AFTER ADR-0125 (2026-08-20)
 # -----------------------------------------------
@@ -98,17 +149,36 @@ name: Release
 #
 # WHAT IS DELIBERATELY STILL AUTOMATIC
 # ------------------------------------
-# Version-PR maintenance (this file's `version-pr` job) stays on push runs —
-# harmless bookkeeping, and #4935 must keep regenerating. Release/D4/image
-# backfill for an already-published version stays on push runs — it is the
-# #4900 repair, and it cannot mint a version. `npm publish` and `git push --tags`
-# still live in exactly one job, and that job cannot start without a human
-# approving it.
+# Version-PR maintenance (this file's `version-pr` job) still runs unattended —
+# harmless bookkeeping, and #4935 must keep regenerating — it just runs on a
+# 6-hourly schedule instead of on every push (#11233). A `schedule` trigger
+# reaching this job is not a loosening: the job has no publish capability by
+# construction, so the event that starts it cannot change what it is able to do.
+# Release/D4/image backfill for an already-published version stays on push runs —
+# it is the #4900 repair, and it cannot mint a version. `npm publish` and
+# `git push --tags` still live in exactly one job, that job is reachable from
+# `push` and from the repair dispatch ONLY — never from `schedule`, never from a
+# refresh dispatch — and it cannot start without a human approving it.
 
 on:
   push:
     branches:
       - main
+  # Version-PR bookkeeping only (#11233). GitHub runs `schedule` on the DEFAULT
+  # BRANCH exclusively, which is the ref `version-pr` may ever regenerate from,
+  # so the trigger cannot reach a ref the job is not meant to touch. Six-hourly
+  # is the stale-window budget: #4935 renders changesets that are already
+  # committed on main, so lateness costs nothing that cannot be bought back on
+  # demand with `refresh_version_pr` below.
+  #
+  # ⚠️ Scheduled runs are queued, not guaranteed on the minute — GitHub delays
+  # or drops them under load, and disables them entirely after 60 days of
+  # repository inactivity. Both are acceptable HERE and would not be on a
+  # publishing lane: a refresh that arrives late leaves #4935 stale, which is
+  # visible on the PR and fixable by one dispatch. This is a second reason the
+  # publish lane must never be reachable from `schedule`.
+  schedule:
+    - cron: '0 */6 * * *'
   # The repair lane (ADR-0125 D4). Takes NO version: both lanes audit main the
   # same way. `force` exists for the one case the push lane's predicate cannot
   # see — a publish that died having already shipped the @objectstack/cli canary
@@ -126,6 +196,20 @@ on:
         required: false
         default: false
         type: boolean
+      # The on-demand half of #11233's schedule. Its ONLY effect is to move this
+      # dispatch onto the bookkeeping lane: `version-pr` requires it, and both
+      # `release-integrity` and `publish` refuse a dispatch that carries it. It
+      # therefore cannot widen anything — it is strictly subtractive, the one
+      # input in this file that can only ever cause LESS to run.
+      refresh_version_pr:
+        description: >-
+          Regenerate the "chore: version packages" PR (#4935) now instead of
+          waiting for the next 6-hourly refresh. Runs the bookkeeping lane ONLY:
+          no audit, no publish, no deployment queued at the `release`
+          environment. Leave unchecked to use the publish repair lane.
+        required: false
+        default: false
+        type: boolean
 
 # ⛔ NO workflow-level concurrency — per-JOB groups below, deliberately
 # (ADR-0125 D5).
@@ -139,23 +223,42 @@ on:
 #
 # Worse than not separating: a job waiting on the `release` environment approval
 # holds its run IN PROGRESS for as long as the maintainer takes. Under one
-# shared group every main push in that window would queue as pending and evict
+# shared group every other run in that window would queue as pending and evict
 # the one before it, so an hour spent deciding would silently stop the Version
 # Packages PR from regenerating. Per-job groups keep the waiting publish from
-# touching the bookkeeping lane at all.
+# touching the bookkeeping lane at all. #11233 sharpened this rather than
+# retiring it: the runs that would be evicted are now the 6-hourly refreshes and
+# any on-demand one, and a refresh is exactly what someone reaches for while a
+# release is mid-approval.
 
 jobs:
   # ══════════════════════════════════════════════════════════════════════════
   # PUSH LANE 1 — version-PR bookkeeping. Structurally cannot publish.
   # ══════════════════════════════════════════════════════════════════════════
   version-pr:
     name: Version PR maintenance
-    if: github.event_name == 'push'
+    # ⛔ NOT `push` (#11233). On push this job force-pushed #4935 on every one of
+    # main's ~18 daily landings, so the PR's own CI could never converge and the
+    # PR could never merge. The scheduled tick is the refresh; the dispatch input
+    # is the same refresh on demand.
+    #
+    # `inputs.refresh_version_pr` is guarded by the event test rather than read
+    # bare: the `inputs` context exists only on `workflow_dispatch`, so on a
+    # `schedule` run it is null — and `null` is falsy, which would be the right
+    # answer by accident. Say which event we are on, so the guard states the lane
+    # split instead of leaning on a context's emptiness.
+    if: >-
+      github.event_name == 'schedule' ||
+      (github.event_name == 'workflow_dispatch' && inputs.refresh_version_pr)
     runs-on: ubuntu-latest
-    # Serialise against itself so two landings cannot race the force-push to
-    # `changeset-release/main`; never cancel in progress. An evicted PENDING run
-    # is harmless here — this job regenerates the PR from scratch, so the newest
-    # run's result is the one that was wanted anyway.
+    # Serialise against itself so two refreshes cannot race the force-push to
+    # `changeset-release/main`; never cancel in progress. The races it covers
+    # changed with the trigger (#11233) but did not go away: a scheduled tick can
+    # still overlap the previous one if a refresh runs long, and an on-demand
+    # dispatch is most likely to be fired precisely when someone is impatient
+    # with a tick already in flight. An evicted PENDING run is harmless here —
+    # this job regenerates the PR from scratch, so the newest run's result is the
+    # one that was wanted anyway.
     concurrency:
       group: release-version-pr-${{ github.ref }}
       cancel-in-progress: false
@@ -246,10 +349,23 @@ jobs:
   # ══════════════════════════════════════════════════════════════════════════
   release-integrity:
     name: Release integrity (audit + no-mint backfill)
-    # Runs on BOTH events now (ADR-0125 D1): it is the single place that reads
-    # what main carries and asks npm whether that version exists, so the push
-    # lane and the repair lane converge on ONE predicate and one guard instead
-    # of two code paths that can drift.
+    # Runs on both RELEASE events (ADR-0125 D1): it is the single place that
+    # reads what main carries and asks npm whether that version exists, so the
+    # push lane and the repair lane converge on ONE predicate and one guard
+    # instead of two code paths that can drift.
+    #
+    # This `if:` is new with #11233 and is the reason that sentence still holds.
+    # The job used to carry no `if:` at all, which meant "every event this file
+    # has" — correct while the file had exactly the two release events, and
+    # wrong the moment a third arrived. Without it the 6-hourly tick and every
+    # on-demand refresh would run a full release audit, and each one that found
+    # main's version absent from npm would queue a deployment at the `release`
+    # environment for a maintainer to dismiss. The audit mints nothing, so this
+    # is not a safety guard; it is the noise guard the collision section above
+    # argues for. Bookkeeping events do not get a release audit.
+    if: >-
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_dispatch' && !inputs.refresh_version_pr)
     runs-on: ubuntu-latest
     # Serialised: its backfills create GitHub Releases and push a runtime image,
     # and two runs doing that at once is not a state worth reasoning about.
@@ -459,10 +575,21 @@ jobs:
     # than `||`, so `success() && A || B` would let the force branch publish on
     # top of a FAILED audit — and the audit is what computes the version this
     # job's name, guard and tag all read. If the audit dies, nothing publishes.
+    #
+    # `!inputs.refresh_version_pr` on the force branch is #11233's half, and it
+    # is written even though it is currently redundant. A refresh dispatch skips
+    # `release-integrity`, and a SKIPPED `needs` job makes `success()` false — so
+    # the belt already holds (the `docker` job below documents that same GitHub
+    # behaviour from the other direction). Redundant is not the same as
+    # unnecessary: what makes the force branch safe would then be a fact about a
+    # DIFFERENT job's `if:`, discoverable only by reading it, and the next person
+    # to touch either guard gets no warning. This is the one job in the
+    # repository that publishes; its guard states its own preconditions.
     if: >-
       success() &&
       (needs.release-integrity.outputs.publish-pending == 'true' ||
-       (github.event_name == 'workflow_dispatch' && inputs.force))
+       (github.event_name == 'workflow_dispatch' && inputs.force &&
+        !inputs.refresh_version_pr))
     runs-on: ubuntu-latest
     # One publish at a time per ref, and never cancelled — a run cancelled
     # mid-`changeset publish` is the state that leaves a fixed group half on npm.
@@ -748,11 +875,17 @@ jobs:
     # Called as a reusable workflow so the same build can be re-run manually via
     # workflow_dispatch (e.g. base-image CVE rebuilds) — see docker-publish.yml.
     #
-    # `!cancelled()` rather than the default implicit success(): exactly one of
+    # `!cancelled()` rather than the default implicit success(): at most one of
     # the two upstream jobs runs on any given event, so the other is always
     # SKIPPED — under the implicit success() this job would then never run at
     # all. It also survives a publish job that reached npm and then died
     # (#4900). The outputs are the gate; the jobs' statuses are not.
+    #
+    # On #11233's bookkeeping events (`schedule`, or a dispatch carrying
+    # `refresh_version_pr`) NEITHER upstream job runs, which is why "at most"
+    # replaced "exactly". Nothing else here changes: both outputs are then unset,
+    # unset compares false against 'true', and this job stays skipped — the
+    # outputs were already the gate, so a third event needed no new condition.
     if: ${{ !cancelled() && (needs.release-integrity.outputs.published == 'true' || needs.publish.outputs.published == 'true') }}
     permissions:
       contents: read