Repository navigation
Commit 1491787
ci(release): add the dispatch-only next snapshot lane (ADR-0125 amendment) (#30799)
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiNjyvCdXYygFqntMNR7S2dW)_
Part of #30591
Ruling-ref: 6663894403
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:Release 工作流新增一条只能手动触发的 `next` 快照通道。勾选 `snapshot_next` 并在
`release` 环境批准后,它把 main 上最新一个全量测试在本提交上全绿的版本,以 `0.0.0-next-时间戳` 发布到 npm 的
`next` 标签。不打 git tag,不建 GitHub Release,不碰 Version Packages PR,不动
`latest`。
- **为什么改**:ADR-0125 的 2026-11-05 修订(#29466 的裁决)要求:应用方当天就需要的修复,可以先装
`next`,不必等下一个稳定版;用 `latest` 的用户没有任何变化。
- **风险与回滚**:快照触发与稳定通道互斥。稳定通道三个 job 的 `if:`
只做减法,另有自测钉住。审批页上的任务名与稳定发布的提示不同,不会被当成稳定发布批准。回滚就是 revert 本 PR;已发布的快照只占
`next`,下一次稳定发布会把 `next` 移回稳定版。注意:`@objectstack/service-push` 还没在 npm
首发,在稳定通道首发它之前,本通道会拒绝发布(这是设计要求)。
- **先看**:① `.github/workflows/release.yml`:文件末尾两个新 job,以及
`release-integrity` / `full-battery` / `publish` 三处新增的
`!inputs.snapshot_next`;② `scripts/ci/snapshot-next.mjs`:`guard` 与首发规则
`debutRefusals`;③ `scripts/release-snapshot-publish.sh`:唯一的发布命令行。
- **两分钟验证**:运行 `node scripts/ci/snapshot-next.mjs --self-test`,预期最后一行是
`snapshot-next: self-test OK -- 68 case(s) across 11 batteries`。
- **需要你做的**:等席位的独立契约评审通过后,审阅并合并本 PR(`release.yml` 是受管面)。
## What changes
ADR-0125's `## Amendment (2026-11-05, #29466)` lists what the lane must
satisfy. Each item and where this PR meets it:
- **Dispatch-only and exclusive.** A new `workflow_dispatch` input,
`snapshot_next` (boolean, default false), selects the lane.
`release-integrity`, the stable `full-battery` gate (force branch) and
`publish` (force branch) now also require `!inputs.snapshot_next`. These
are strictly subtractive `if:` edits, the same shape as
`!inputs.refresh_version_pr`. The two new jobs run only on
`workflow_dispatch && inputs.snapshot_next &&
!inputs.refresh_version_pr`. `stale-prompts`, `version-pr` and `docker`
are unchanged. A snapshot dispatch therefore queues no stable prompt
that the stale-prompt sweep could not reach. Combined inputs:
- snapshot + refresh runs `version-pr` only, following the existing
refresh-wins precedent.
- snapshot + force runs the snapshot lane only; `force` is never read
there.
- **The commit, distance zero.** `scripts/ci/scheduled-full-run.mjs`
gains machine-readable output:
- `--json`: stdout carries exactly one JSON record and prose goes to
stderr.
- `--require-distance-zero`: refuses unless each gate workflow's
deciding run is ON the release commit.
- `--snapshot-commit --from SHA`: walks main's first-parent history and
picks the newest commit at which both CI and Lint & Type Check decide
green at distance zero.
- `releaseGateVerdict` now also returns `chosen` rows and
`distanceZero`. The stable `--release-gate` output and verdict are
unchanged when the new flag is absent.
- The preflight selects the commit with `--snapshot-commit`, confirms it
with `--release-gate --release-commit C --require-distance-zero --json`,
and checks the record with `jq`. The publish job checks out exactly that
commit and re-asserts that it is an ancestor of `origin/main`.
- **Not during an RC cycle.** `snapshot-next.mjs preflight` refuses when
`.changeset/pre.json` exists with `mode: pre` (`preModeRefusal`).
- **Workspace only.** The publish job runs the bare `pnpm exec changeset
version --snapshot next` (never `pnpm run version`) and asserts the
version is `0.0.0-next-` followed by 14 digits. It commits nothing, and
its checkout holds no push credential (`persist-credentials: false`,
`contents: read`). It then runs `bash
scripts/release-snapshot-publish.sh`, whose one publish line is
`changeset publish --tag next --no-git-tag`. The script is preceded by
the same `check-published-dist-tooling --no-build` refusal the stable
publish runs. There is no tag push, no GitHub Release and no Version
Packages PR write.
- **The guard and the debut rule.** `scripts/ci/snapshot-next.mjs` (new,
with `--self-test`):
- `preflight` reads every member of the 109-package fixed group on npm
(abbreviated packument). It refuses on any member with no version
(`debutRefusals`), and fails closed on any unread member. Today that is
`@objectstack/service-push`.
- `guard` runs before the publish. It checks that:
- the fixed group equals the publishable set, and every member is at one
snapshot version;
- no `publishConfig.tag`, `.npmrc` `tag=` or `npm_config_tag` overrides
the tag (no value is printed);
- the `changeset publish-plan` covers the whole group;
- every packed manifest (`changeset pack`, so pnpm has substituted
`workspace:`) carries the snapshot version, holds no `workspace:` range,
and has every intra-group range satisfied by the snapshot.
- `verify` runs after the publish. It reads `next` back at the snapshot
version and treats any `latest` move onto a snapshot as an incident. ⛔
Nothing in the lane writes `latest`.
- **The approval screen.** `snapshot-next` is held at `environment:
release`. Its name is `Snapshot next of main COMMIT (awaiting
approval)`, and the self-test pins that it does not match
`PUBLISH_JOB_NAME` from `release-pending-publish.mjs`. It has its own
concurrency group, `release-snapshot-next-REF` with `cancel-in-progress:
false`, so a waiting snapshot never holds `release-publish-REF`.
- **The dry run.** `node scripts/ci/snapshot-next.mjs dry-run` runs the
preflight, the version step and the guard's pack. It prints each package
with its version, dist-tag and intra-group ranges, then restores the
tree. It publishes nothing and reads no token. The preflight job runs it
on every snapshot dispatch, before approval.
- **Docs.** The release-channels table in `docs/releases-maintenance.md`
gains the snapshot `next` row, plus a paragraph on sort order and on AI
seats never dispatching the lane.
- **Gates that read release.yml.**
- `scripts/pm/fleet-write/validate.mjs`: pins for the declared inputs
and the job roster (eight jobs), and the mutation anchor for
`release-integrity`'s guard.
- `.github/workflows/lint.yml`: wires `snapshot-next.mjs --self-test`
(step id `snapshot-lane-guard-self-test`).
## Tests
- `node scripts/ci/snapshot-next.mjs --self-test`: 68 cases across 11
batteries. Coverage includes:
- Pre-mode refusal, debut refusal, tag overrides, plan and
packed-manifest problems, and the verify incident rules.
- Mutation cases on the real release.yml and the publish script. Each
fires when an `if:` negation, the environment, the name shape, the bare
version command or the publish line is removed or reshaped.
- Exclusivity evaluated through fleet-write's own `jobsStartedBy` over
every event and input combination. Push, schedule, repair, force and
refresh never reach the snapshot jobs. A snapshot dispatch reaches no
stable job.
- `node scripts/ci/scheduled-full-run.mjs --self-test`: a new battery,
"release gate: distance zero and the snapshot commit, machine-readable"
(11 cases). The battery floor was raised from 7 to 8. On the recorded
fixture, the stable gate verdict is unchanged.
- `pnpm check:pm-fleet-write-validate`: 329 cases pass with the updated
pins.
## Acceptance notes
- Acceptance item 1 (the dry run) is met. Its output is below.
- Acceptance item 2 (the first real snapshot's `npm view` reading) waits
for `@objectstack/service-push` to debut through the stable lane, which
is why this PR says `Part of`.
- Version shape: changesets v3 with no snapshot template yields
`0.0.0-next-YYYYMMDDHHMMSS`. The docs table spells that shape.
- The publish job also runs `release-spec-changes.sh --generate` and
then `--verify`, so the spec tarball ships its two ADR-0087 projections,
as the stable publish does. The snapshot lane builds no Docker image,
runs no dist-tag sweep and cuts no GitHub Release.
- The dry run owns the tree while it runs. It refuses a dirty tree, then
restores tracked paths with `git restore` and removes only the untracked
files it created.
## Verification
<details>
<summary>Dry run on 75a0ac4 (local, no publish, no npm token):
REFUSED on the debut rule, guard clean</summary>
```text
snapshot-next dry-run: nothing is published, tagged or pushed; no npm token is read.
preflight: 109 fixed-group member(s) read on npm; 1 refusal(s), 0 unread.
REFUSED @objectstack/service-push has no version on npm: its first publish would take `latest` whatever tag it carries. The stable lane debuts it; no snapshot is cut until it has.
version: changeset version --snapshot next (bare; never `pnpm run version`)
version step moved 611 path(s): 122 package.json, 122 CHANGELOG.md, 367 .changeset/ file(s), 0 other -- none of it is ever committed.
guard: 109 member(s) · version 0.0.0-next-20261106032733 · tag next · planned 109 · packed 109 · 540 intra-group range(s) in the packed manifests, all checked against the snapshot
would publish (name · version · dist-tag · intra-group ranges in the packed manifest):
@object-ui/auth · 0.0.0-next-20261106032733 · next · 1
@object-ui/cli · 0.0.0-next-20261106032733 · next · 4
... (109 rows, every one at tag next; full list in the os-dev-report on the card)
@objectstack/cli · 0.0.0-next-20261106032733 · next · 52
@objectstack/runtime · 0.0.0-next-20261106032733 · next · 21
@objectstack/service-push · 0.0.0-next-20261106032733 · next · 2
@objectstack/spec · 0.0.0-next-20261106032733 · next · 0
@objectstack/verify · 0.0.0-next-20261106032733 · next · 35
create-objectstack · 0.0.0-next-20261106032733 · next · 0
tree: restored to HEAD
VERDICT: REFUSED -- 1 preflight refusal(s), 0 unread, 0 guard problem(s). The lane would publish nothing.
```
</details>
<details>
<summary>Derived gates on 75a0ac4: 67 derived, 67 run, all exit 0;
--ran reconciled</summary>
```text
node scripts/check-adr-links.mjs (+ --self-test) :: exit 0
node scripts/check-closing-keyword-parity.mjs (+ --self-test) :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/check-declaration-mirrors.mjs (+ --self-test) :: exit 0
node scripts/check-merged-branch-reaper-outcome.mjs (+ --self-test) :: exit 0
node scripts/check-self-test-wired.mjs (+ --self-test) :: exit 0
node scripts/check-self-test-workflow-commands.mjs (+ --self-test) :: exit 0
node scripts/check-step-collectors.mjs (+ --self-test) :: exit 0
node scripts/check-whole-set-label-write.mjs (+ --self-test) :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/scheduled-full-run.mjs --self-test :: exit 0
node scripts/ci/snapshot-next.mjs --self-test :: exit 0
node scripts/docs-audit/check-drift-comment.mjs :: exit 0
node scripts/pm/bare-root-worklist.mjs --self-test :: exit 0
node scripts/pm/ci-failure.mjs --self-test :: exit 0
node scripts/release-dist-tags.mjs --self-test :: exit 0
node scripts/release-verify-npm.mjs --self-test :: exit 0
pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:aggregator-roster :: exit 0
pnpm check:bash32-floor :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:cli-command-ids :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:declared-population-live :: exit 0
pnpm check:doc-authoring :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:entry-guard :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:node-version :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:parse-guard :: exit 0
pnpm check:pm-close-cards :: exit 0
pnpm check:pm-dispatch-gates :: exit 0
pnpm check:pm-expected-skips :: exit 0
pnpm check:pm-fleet-write-dispatch :: exit 0
pnpm check:pm-fleet-write-execute :: exit 0
pnpm check:pm-fleet-write-validate :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-issue-create :: exit 0
pnpm check:pm-issue-transfer :: exit 0
pnpm check:pm-label-write :: exit 0
pnpm check:pm-post-stamped :: exit 0
pnpm check:pm-record-recognisers :: exit 0
pnpm check:pnpm-acquisition :: exit 0
pnpm check:pnpm-filter-targets :: exit 0
pnpm check:pnpm-flag-spellings :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:required-contexts :: exit 0
pnpm check:scripts-symbol-anchors :: exit 0
pnpm check:select-gate-families :: exit 0
pnpm check:shard-attestation :: exit 0
pnpm check:stall-guard-budget :: exit 0
pnpm check:stall-guard-headroom :: exit 0
pnpm check:type-check-coverage :: exit 0
pnpm check:type-check-debt :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:workflow-status-functions :: exit 0
pnpm check:workflow-step-name-quoting :: exit 0
Run reconciliation — 67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN.
```
`check:doc-formula-expressions` first exited 3 (its build prerequisite
was missing). It went green after building `@objectstack/formula` and
`@objectstack/lint`.
</details>
`skip-changeset`: the diff touches only `.github/workflows/**`,
`scripts/**` and `docs/**`, none of which is in any package's `files[]`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 0cba0ce commit 1491787
7 files changed
Lines changed: 1959 additions & 37 deletions
File tree
- .github/workflows
- docs
- scripts
- ci
- pm/fleet-write
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3152 | 3152 | | |
3153 | 3153 | | |
3154 | 3154 | | |
| 3155 | + | |
| 3156 | + | |
| 3157 | + | |
| 3158 | + | |
| 3159 | + | |
| 3160 | + | |
| 3161 | + | |
| 3162 | + | |
| 3163 | + | |
3155 | 3164 | | |
3156 | 3165 | | |
3157 | 3166 | | |
| |||
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
190 | 190 | | |
191 | 191 | | |
192 | 192 | | |
193 | | - | |
| 193 | + | |
| 194 | + | |
194 | 195 | | |
195 | 196 | | |
196 | 197 | | |
197 | | - | |
198 | | - | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
199 | 206 | | |
200 | 207 | | |
201 | 208 | | |
| |||
228 | 235 | | |
229 | 236 | | |
230 | 237 | | |
231 | | - | |
232 | | - | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
233 | 242 | | |
234 | 243 | | |
235 | 244 | | |
| |||
0 commit comments