@futurelastic/colab-handbook 1.12.0-rc.19 → 1.12.0-rc.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -1432,7 +1432,11 @@ function auditRepo(target, ctx) {
1432
1432
  if (grant) {
1433
1433
  const v = releasePolicy.finalGrantVerdict(src.issue ? src.issue(grant.issue) : null, { issue: grant.issue, trust: trustHumansLib.parseTrustHumans(cfg) });
1434
1434
  info.releaseFinalGrant = { issue: grant.issue, ok: v.ok, ruledBy: v.ruledBy };
1435
- if (!v.ok) fail(`release.final: auto on deploy-tag has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, An operator-granted automatic final)`);
1435
+ if (!v.ok) {
1436
+ fail(rel.effective.route === releasePolicy.FAST_ROUTE
1437
+ ? `route: deploy-tag-fast has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, A final on every green head)`
1438
+ : `release.final: auto on deploy-tag has no resolvable operator grant — ${v.detail} (CONVENTIONS.md §6, An operator-granted automatic final)`);
1439
+ }
1436
1440
  }
1437
1441
  }
1438
1442
 
@@ -1642,6 +1646,7 @@ function auditRepo(target, ctx) {
1642
1646
  const deployWorkflows = workflows.filter((f) => /^deploy[-.]/.test(f));
1643
1647
  checkPrereleaseTagTrigger(src, workflows, deploy, fail, warn);
1644
1648
  checkReleaseAuto(src, workflows, cfg, warn);
1649
+ checkFastRouteDeploy(src, workflows, cfg, fail);
1645
1650
  checkPrivateNpm(src, workflows, fail, warn);
1646
1651
 
1647
1652
  const runbook = cfg && "runbook" in cfg ? cfg.runbook : null;
@@ -2537,7 +2542,8 @@ function releaseAutoFindings({ readFile, workflows, cfg }) {
2537
2542
  const text = readFile(`.github/workflows/${wf}`);
2538
2543
  if (!text || !RELEASE_AUTO_RUN.test(text)) continue;
2539
2544
  const runsCut = /\brelease\s+cut\s+--auto\b/.test(text);
2540
- if (runsCut && effective && effective.candidates === "off") {
2545
+ // #446: on deploy-tag-fast candidates are off by design — `cut --auto` tags the final itself.
2546
+ if (runsCut && effective && effective.candidates === "off" && effective.finalize !== "on-green-head") {
2541
2547
  out.push(`${wf} runs \`colab release cut --auto\`, but the release rung leaves candidates off on this descriptor (${effective.route === null ? "no route" : `route ${effective.route}`}) — every run refuses; remove the workflow, or change exposure/deploy/release: deliberately (CONVENTIONS.md §6)`);
2542
2548
  }
2543
2549
  const publishesHere = /\bgh\s+release\s+create\b/.test(text) || /action-gh-release/.test(text) || /uses:\s*\.\/\.github\/workflows\//.test(text);
@@ -2561,6 +2567,42 @@ function checkReleaseAuto(src, workflows, cfg, warn) {
2561
2567
  for (const text of releaseAutoFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) warn(text);
2562
2568
  }
2563
2569
 
2570
+ // ---- route deploy-tag-fast: the final is deployed in the run that tags it (#446) ----------------
2571
+ // A tag pushed with GITHUB_TOKEN starts no `push: tags` workflow, so on this route the workflow that
2572
+ // runs `colab release cut --auto` must itself deploy what it tagged — templates/release-auto.yml's
2573
+ // `deploy` job reads the cut step's `final` output. Fail, not warn: without it every final reaches
2574
+ // the Release page and `stable` while production never moves, and nothing says so. Also fails the
2575
+ // template's deploy step left unedited (it fails every run by design, but the audit says why first).
2576
+ // What the audit cannot check is that the deploy really rolls back on a failed health check —
2577
+ // release.rollback: auto is the operator's statement of that, which is why the grant is required.
2578
+ const FAST_DEPLOY_CONSUMER = /outputs\.(final|deploy-tag)\b|\.final\s*\/\/|jq -r '\.final\b/;
2579
+ const FAST_DEPLOY_UNEDITED = /the deploy step of release-auto\.yml was never edited/;
2580
+ function fastRouteDeployFindings({ readFile, workflows, cfg }) {
2581
+ const effective = cfg ? releasePolicy.evaluateRelease(cfg).effective : null;
2582
+ if (!effective || effective.finalize !== "on-green-head") return [];
2583
+ const cutters = (workflows || []).filter((wf) => {
2584
+ const t = readFile(`.github/workflows/${wf}`);
2585
+ return t && /\brelease\s+cut\s+--auto\b/.test(t);
2586
+ });
2587
+ if (!cutters.length) {
2588
+ return ["route: deploy-tag-fast but no workflow runs `colab release cut --auto` — nothing tags or deploys a final; copy templates/release-auto.yml (CONVENTIONS.md §6, A final on every green head)"];
2589
+ }
2590
+ const out = [];
2591
+ const deploying = cutters.filter((wf) => FAST_DEPLOY_CONSUMER.test(readFile(`.github/workflows/${wf}`)));
2592
+ if (!deploying.length) {
2593
+ out.push(`route: deploy-tag-fast, but ${cutters.join(", ")} runs \`colab release cut --auto\` and deploys nothing from its result — a tag pushed with GITHUB_TOKEN starts no \`push: tags\` run, so the final would never deploy; deploy in the same run (templates/release-auto.yml, job \`deploy\`)`);
2594
+ }
2595
+ for (const wf of deploying) {
2596
+ if (FAST_DEPLOY_UNEDITED.test(readFile(`.github/workflows/${wf}`))) {
2597
+ out.push(`route: deploy-tag-fast, but ${wf}'s deploy step is still the template's unedited placeholder — every final would be tagged and published but not deployed; replace it with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)`);
2598
+ }
2599
+ }
2600
+ return out;
2601
+ }
2602
+ function checkFastRouteDeploy(src, workflows, cfg, fail) {
2603
+ for (const text of fastRouteDeployFindings({ readFile: (p) => src.readFile(p), workflows, cfg })) fail(text);
2604
+ }
2605
+
2564
2606
  // ---- a private repo never publishes to public npm (#432) ---------------------
2565
2607
  // Visibility is read from the GitHub API, and only when the repo has an npm surface at all (so an
2566
2608
  // npm-free repo costs no API call). Unreadable / no remote → reported as a warn, never passed.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.19"
30
+ "version": "1.12.0-rc.20"
31
31
  }
@@ -24,6 +24,8 @@
24
24
  # any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
25
25
  # project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
26
26
  # comment above that job
27
+ # the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
28
+ # deploy-tag-fast only "DEPLOYING IN THIS RUN" below
27
29
  #
28
30
  # Every decision — whether a candidate is owed, which bump, whether the test period
29
31
  # elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
@@ -77,6 +79,15 @@
77
79
  # workflow pushes either — on a `deploy: tag` repo the final is a human act anyway, and
78
80
  # finalize --auto only posts the command for it.
79
81
  #
82
+ # DEPLOYING IN THIS RUN (deploy-tag-fast, #446). On a `deploy: tag` repo whose operator granted
83
+ # route `deploy-tag-fast` (release.final-grant + release.health-url + release.rollback: auto),
84
+ # `colab release cut --auto` tags the FINAL vX.Y.Z on every green main head — no candidate, no
85
+ # test period — and the `deploy` job below deploys that tag in this same run, then polls
86
+ # release.health-url until it reports the version. Its deploy step is an EDIT point: replace it
87
+ # with your deploy (it fails loudly until you do). On every other route the job is skipped and the
88
+ # run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
89
+ # tags a head that release.final-spacing held back sooner.
90
+ #
80
91
  # IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
81
92
  # pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
82
93
  # checks recorded in the tag message) and — only on a repo granting unattended promotion — the
@@ -155,6 +166,9 @@ jobs:
155
166
  npm-dir: ${{ steps.npm-target.outputs.dir }}
156
167
  npm-gate: ${{ steps.npm-target.outputs.gate }}
157
168
  npm-package: ${{ steps.npm-target.outputs.package }}
169
+ # What the deploy job below needs (#446) — empty unless this run tagged a deploy-tag-fast final.
170
+ deploy-tag: ${{ steps.cut.outputs.final }}
171
+ health-url: ${{ steps.cut.outputs.health-url }}
158
172
  env:
159
173
  GH_TOKEN: ${{ github.token }}
160
174
  steps:
@@ -261,6 +275,12 @@ jobs:
261
275
  TAG="$(jq -r '.tag' "$OUT")"
262
276
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
263
277
  echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
278
+ # #446: on route deploy-tag-fast the cut IS the final, and the deploy job deploys it in
279
+ # this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow).
280
+ if [ "$(jq -r '.final // false' "$OUT")" = "true" ]; then
281
+ echo "final=$TAG" >> "$GITHUB_OUTPUT"
282
+ echo "health-url=$(jq -r '.deploy.healthUrl // ""' "$OUT")" >> "$GITHUB_OUTPUT"
283
+ fi
264
284
  elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
265
285
  echo "No-op: nothing owed, head already a candidate, inside a declared cadence window, or main's head is not a promotion." | tee -a "$GITHUB_STEP_SUMMARY"
266
286
  elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
@@ -493,3 +513,60 @@ jobs:
493
513
  gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
494
514
  echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
495
515
  done
516
+
517
+ # ---------------------------------------------------------------------------------------------
518
+ # deploy (#446) — route deploy-tag-fast only: deploys the final the release job just tagged, in
519
+ # this same run, then verifies it. Skipped on every other route (deploy-tag stays empty).
520
+ #
521
+ # Same run, never a tag-triggered deploy workflow: a tag pushed with GITHUB_TOKEN starts no
522
+ # `push: tags` run, so a separate deploy-on-tag workflow would never fire for this final.
523
+ #
524
+ # The health check is the handbook's half of the "health-gated deploy with automatic rollback"
525
+ # the route requires: it fails this job when release.health-url does not report the version in
526
+ # time. The ROLLBACK is your deploy's own (release.rollback: auto is your statement that it has
527
+ # one) — this job does not roll anything back. A failed deploy leaves the tag standing and this
528
+ # run red; fix forward, or re-run the failed job to deploy the same tag again.
529
+ deploy:
530
+ name: Deploy the final (deploy-tag-fast)
531
+ needs: release
532
+ if: needs.release.outputs.deploy-tag != ''
533
+ runs-on: ubuntu-latest # EDIT: the runner your deploy needs (self-hosted label, etc.).
534
+ environment: production # EDIT: the GitHub environment holding your deploy secrets, or remove.
535
+ permissions:
536
+ contents: read # check out the tag
537
+ env:
538
+ TAG: ${{ needs.release.outputs.deploy-tag }}
539
+ HEALTH_URL: ${{ needs.release.outputs.health-url }}
540
+ HEALTH_TIMEOUT_SECONDS: "600" # EDIT: how long the new version may take to report itself.
541
+ steps:
542
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
543
+ with:
544
+ ref: refs/tags/${{ needs.release.outputs.deploy-tag }}
545
+ persist-credentials: false # nothing here pushes
546
+
547
+ # EDIT: replace this step's body with your deploy of "$TAG" (an image push + rollout, an
548
+ # SSH script, a platform CLI). It must roll back by itself when the new version fails its
549
+ # health check — that is what release.rollback: auto declares. Until edited it fails, so a
550
+ # final is never reported deployed when nothing deployed it.
551
+ - name: Deploy the final (EDIT)
552
+ run: |
553
+ set -euo pipefail
554
+ echo "::error::the deploy step of release-auto.yml was never edited — $TAG is tagged and published but NOT deployed. Replace this step with your deploy (templates/release-auto.yml, DEPLOYING IN THIS RUN)."
555
+ exit 1
556
+
557
+ - name: Verify the health endpoint reports the final
558
+ run: |
559
+ set -uo pipefail
560
+ VERSION="${TAG#v}"
561
+ DEADLINE=$(( $(date +%s) + HEALTH_TIMEOUT_SECONDS ))
562
+ while :; do
563
+ BODY="$(curl -fsS --max-time 10 "$HEALTH_URL" 2> /dev/null || true)"
564
+ case "$BODY" in
565
+ *"$VERSION"*) echo "$HEALTH_URL reports $VERSION — $TAG is live" | tee -a "$GITHUB_STEP_SUMMARY"; exit 0 ;;
566
+ esac
567
+ if [ "$(date +%s)" -ge "$DEADLINE" ]; then
568
+ echo "::error::$HEALTH_URL did not report $VERSION within ${HEALTH_TIMEOUT_SECONDS}s — the deploy's own rollback should have restored the previous version; $TAG stays tagged"
569
+ exit 1
570
+ fi
571
+ sleep 10
572
+ done
package/tools/colab CHANGED
@@ -1235,6 +1235,20 @@ Refuses, naming each failed condition (all are reported, not just the first):
1235
1235
  There the bump reads the promoted commits (main's merge subject is skipped),
1236
1236
  and a switch-removal child counts when its Closes #N was promoted.
1237
1237
 
1238
+ Route deploy-tag-fast (#446) — a deploy: tag repo with the operator's grant and a declared health gate:
1239
+ --auto tags the FINAL vX.Y.Z on main's green head — no candidate, no test period — publishes it as
1240
+ the latest GitHub Release, moves the stable channel, and prints final/deploy in --json so the
1241
+ release workflow's deploy job deploys it in the same run. Without --auto it refuses: a final cut by
1242
+ hand would reach production with no deploy job behind it. Five more conditions there:
1243
+ spacing release.final-spacing (default and floor 1h) since the newest final — inside
1244
+ it the run is a NO-OP; the first run after it tags main's head
1245
+ already-final main's head already carries a final — a NO-OP
1246
+ final-grant release.final-grant's decision still resolves (recorded, trusted, not reopened)
1247
+ release-hold an open issue carries the release-hold label (a human veto)
1248
+ migration-grant a migration since the last final with no grant on the version's tracking
1249
+ issue — refused; a non-dry run opens "release: vX.Y.Z" if needed and posts the
1250
+ one human command (COLAB_HUMAN=1 colab migration-grant <N> --branch vX.Y.Z)
1251
+
1238
1252
  The bump (without --auto) is release-status's semverSuggestion since the last final tag (candidates skipped): fix ->
1239
1253
  patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
1240
1254
  --bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
@@ -1441,6 +1455,75 @@ function measureAutoSignals(repoAbs, { doc, sha, lastFinal, remote, issues, trun
1441
1455
  return { signals, migration: (v) => releaseCut.parseMigrationSection(migrationText, v) };
1442
1456
  }
1443
1457
 
1458
+ /** #446: every final `vX.Y.Z` tag as [{ name, date }] — what release.final-spacing counts. A human's final counts too. */
1459
+ function finalTags(repoAbs) {
1460
+ const fe = git.git(['for-each-ref', 'refs/tags', '--format=%(refname:short)%09%(creatordate:iso-strict)'], repoAbs);
1461
+ return (fe.ok ? fe.stdout.split('\n').filter(Boolean) : []).map((l) => l.split('\t'))
1462
+ .filter(([name]) => releaseCut.parseVersion(name)).map(([name, date]) => ({ name, date }));
1463
+ }
1464
+
1465
+ /**
1466
+ * #446: what route deploy-tag-fast keeps in place of a test period, measured — the operator's grant
1467
+ * (the #441 reader, against trunk's trust-humans), the repo-wide release-hold veto, every migration
1468
+ * since the last final against a grant on the computed version's tracking issue, and the spacing
1469
+ * since the newest final. The version is computed here only to find that tracking issue; decide()
1470
+ * computes it again from the same inputs, so the two cannot disagree.
1471
+ */
1472
+ function measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: paths }) {
1473
+ const grantDecl = policy.effective.finalGrant;
1474
+ const trust = trustAt(repoAbs, `${remote}/main`);
1475
+ const finalGrant = isGhUsable(repoAbs)
1476
+ ? releasePolicy.finalGrantVerdict(git.ghIssueView(repoAbs, grantDecl.issue, ['state', 'labels', 'comments']), { issue: grantDecl.issue, trust })
1477
+ : { ok: false, ruledBy: null, detail: `release.final-grant #${grantDecl.issue} could not be read: gh not usable (${ghUnusableWhy(repoAbs)})` };
1478
+ const holds = releaseCut.holdsVerdict(issues);
1479
+ let tracking = null;
1480
+ let grant = null;
1481
+ const v = auto ? releaseCut.decideAutoVersion({ lastFinal, signals: auto.signals, migration: auto.migration, tags }) : null;
1482
+ if (v && v.ok && issues) {
1483
+ const open = issues.filter((i) => String(i.state || '').toUpperCase() === 'OPEN' && releaseFinalize.parseReleaseMarker(i.body) === v.version);
1484
+ if (open.length) tracking = { number: open[0].number };
1485
+ }
1486
+ if (paths && paths.length) {
1487
+ grant = tracking
1488
+ ? migrationGrant.evaluateIssue(git.ghIssueView(repoAbs, tracking.number, ['state', 'labels', 'comments']), v.version, tracking.number, labels.MIGRATION_GRANT_LABEL, { trust })
1489
+ : { ok: false, reason: 'no tracking issue yet to carry a grant' };
1490
+ if (grant && grant.ok) grant = { ...grant, issue: tracking.number };
1491
+ }
1492
+ const migrations = { ...releaseFinalize.migrationGrantVerdict({ paths, grant, since: lastFinal }), paths: paths || null };
1493
+ const spacing = releaseCut.spacingVerdict({ finals: finalTags(repoAbs), spacingHours: policy.effective.finalSpacingHours, now: new Date().toISOString() });
1494
+ return { finalGrant, holds, migrations, spacing, tracking };
1495
+ }
1496
+
1497
+ /** Post `text` on issue `num` once — idempotent by release-finalize's event marker. */
1498
+ function commentOnce(repoAbs, num, fields, text) {
1499
+ const view = git.ghIssueView(repoAbs, num, ['comments']);
1500
+ if (view && releaseFinalize.hasEvent(view.comments, fields)) return;
1501
+ const r = git.ghIssueComment(repoAbs, num, `${releaseFinalize.eventMarker(fields)}\n${text}`);
1502
+ if (!r.ok) warn(`could not comment on #${num}: ${String(r.stderr || '').split('\n')[0]}`);
1503
+ }
1504
+
1505
+ /**
1506
+ * #426: one "Released in vX.Y.Z" comment on every issue the version carries — the closing references
1507
+ * in (previous final, sha], minus `exclude` (the release tracking issues). Idempotent by event marker.
1508
+ * Shared by `release finalize` and, on route deploy-tag-fast (#446), `release cut`.
1509
+ */
1510
+ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1511
+ const prev = releaseFinalize.previousFinal(tagNames, version);
1512
+ if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
1513
+ const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
1514
+ if (!log.ok) { warn(`could not read ${prev}..${shortSha(sha)} — no issue told it was released in ${version}`); return { range: `${prev}..${version}`, issues: [], posted: [], skipped: [], detail: 'git log failed' }; }
1515
+ const nums = releaseFinalize.carriedIssues(log.stdout.split('\0'), { exclude });
1516
+ const posted = []; const skipped = [];
1517
+ for (const n of nums) {
1518
+ const view = git.ghIssueView(repoAbs, n, ['comments']);
1519
+ if (!view) { skipped.push(n); continue; }
1520
+ if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
1521
+ const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
1522
+ if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
1523
+ }
1524
+ return { range: `${prev}..${version}`, issues: nums, posted, skipped };
1525
+ }
1526
+
1444
1527
  function cmdReleaseCut(argv) {
1445
1528
  const opts = parseArgs(argv, {
1446
1529
  values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
@@ -1485,7 +1568,7 @@ function cmdReleaseCut(argv) {
1485
1568
  const tags = lines(git.git(['tag', '--list'], repoAbs));
1486
1569
  const tagsAtSha = lines(git.git(['tag', '--points-at', sha], repoAbs));
1487
1570
 
1488
- const { ci, suite, schema, switches, issues } = measureCandidateConditions(repoAbs, {
1571
+ const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1489
1572
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1490
1573
  });
1491
1574
  const { manifests, ancestry } = measurePreTag(repoAbs, sha, `${remote}/main`); // #424
@@ -1497,9 +1580,17 @@ function cmdReleaseCut(argv) {
1497
1580
  auto = { signals, migration, cadence, promotion: offTrunk ? measurePromotion(repoAbs, { sha, trunk, remote, fetched: trunkFetch }) : null };
1498
1581
  }
1499
1582
 
1583
+ // #446: route deploy-tag-fast — the grant, the human veto, the migration gate and the spacing are
1584
+ // measured only there, so every candidate route's run is what it was.
1585
+ const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1586
+ const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince }) : {};
1587
+ if (fast && auto) auto.spacing = fastFacts.spacing;
1588
+
1500
1589
  const verdict = releaseCut.decide({
1501
1590
  policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
1502
1591
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1592
+ finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations,
1593
+ trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
1503
1594
  });
1504
1595
 
1505
1596
  let created = false;
@@ -1514,19 +1605,54 @@ function cmdReleaseCut(argv) {
1514
1605
  throw new UserError(`git push ${remote} ${verdict.tag} failed — the local tag was deleted again, nothing is cut (${(push.stderr || '').split('\n')[0]})`);
1515
1606
  }
1516
1607
  created = true;
1517
- published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message });
1608
+ published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message, final: !!verdict.final });
1518
1609
  }
1519
1610
  // #445: the `next` channel names the newest candidate — fast-forwarded in the run that pushed it.
1520
1611
  // Best-effort like the pre-release: the tag already stands, so a channel that cannot move is reported.
1612
+ // #446: a fast-route final moves `stable` instead — it is the newest final, and there is no candidate.
1521
1613
  const channel = verdict.ok && verdict.tag
1522
- ? releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
1614
+ ? releaseChannel.moveChannel(repoAbs, { remote, channel: verdict.final ? releaseChannel.CHANNELS.stable : releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
1523
1615
  : null;
1524
1616
 
1617
+ // #446: the fast route's own writes. A final: every issue it carries hears which version has it, and
1618
+ // an open tracking record for the version is closed. An ungranted migration: the hand-off is posted
1619
+ // on the version's tracking issue (opened if there is none), for a human to grant.
1620
+ let announced = null;
1621
+ let handoff = verdict.handoff || null;
1622
+ if (fast && !opts.dry) {
1623
+ if (created) {
1624
+ const exclude = (issues || []).filter((i) => releaseFinalize.parseReleaseMarker(i.body)).map((i) => i.number);
1625
+ announced = announceCarried(repoAbs, { tagNames: [...tags, verdict.tag], exclude, version: verdict.tag, sha });
1626
+ if (fastFacts.tracking) {
1627
+ commentOnce(repoAbs, fastFacts.tracking.number, { state: 'finalized', tag: verdict.tag }, `**${verdict.tag}** tagged final on \`${shortSha(sha)}\` by route deploy-tag-fast — the release workflow deploys it in this run.`);
1628
+ const r = spawnSync('gh', ['issue', 'close', String(fastFacts.tracking.number)], { cwd: repoAbs, encoding: 'utf8' });
1629
+ if (r.status !== 0) warn(`could not close #${fastFacts.tracking.number}: ${String(r.stderr || '').split('\n')[0]}`);
1630
+ }
1631
+ } else if (handoff && verdict.version) {
1632
+ let num = fastFacts.tracking ? fastFacts.tracking.number : null;
1633
+ if (!num && issues !== null) {
1634
+ const c = spawnSync('gh', ['issue', 'create', '--title', releaseFinalize.trackingTitle(verdict.version), '--body', releaseCut.handoffTrackingBody(verdict.version)], { cwd: repoAbs, encoding: 'utf8' });
1635
+ const m = c.status === 0 ? /\/issues\/([0-9]+)/.exec(c.stdout || '') : null;
1636
+ if (m) num = Number(m[1]);
1637
+ else warn(`could not open the tracking issue for ${verdict.version} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'}) — the hand-off is printed here only`);
1638
+ }
1639
+ if (num) {
1640
+ handoff = releaseCut.migrationHandoff(num, verdict.version);
1641
+ commentOnce(repoAbs, num, { state: 'migration-handoff', version: verdict.version },
1642
+ `**${verdict.version} carries a database migration**, and route deploy-tag-fast never deploys an ungranted one. The one command, run by a human, lets it ride — the next green run then tags and deploys it:\n\n\`\`\`sh\n${handoff}\n\`\`\``);
1643
+ }
1644
+ }
1645
+ }
1646
+
1525
1647
  if (opts.json) {
1526
1648
  print(JSON.stringify({
1527
1649
  repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1528
1650
  ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1529
1651
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1652
+ // #446: present on every route, so the workflow reads one shape — final only on deploy-tag-fast.
1653
+ final: !!verdict.final,
1654
+ deploy: verdict.final && verdict.healthGate ? { healthUrl: verdict.healthGate.url, rollback: verdict.healthGate.rollback } : null,
1655
+ grant: verdict.grant || null, handoff, ...(fast ? { announced } : {}),
1530
1656
  }, null, 2));
1531
1657
  return verdict.ok || verdict.noop ? 0 : 1;
1532
1658
  }
@@ -1540,14 +1666,25 @@ function cmdReleaseCut(argv) {
1540
1666
  for (const c of verdict.checks) print(` ${c.ok ? '✓' : '✗'} ${c.condition.padEnd(width)} ${c.detail}`);
1541
1667
  print('');
1542
1668
  if (verdict.noop) {
1543
- print('· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
1669
+ print(fast
1670
+ ? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
1671
+ : '· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
1544
1672
  return 0;
1545
1673
  }
1546
1674
  if (!verdict.ok) {
1547
1675
  print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
1676
+ if (handoff) print(`\nA migration rides this release. The one command, for a human to run:\n ${handoff}`);
1548
1677
  return 1;
1549
1678
  }
1550
- if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
1679
+ if (verdict.final) {
1680
+ if (opts.dry) print(`[--dry] would tag the final ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub Release and move the stable channel — the workflow's deploy job would then deploy it and check ${verdict.healthGate.url}. Nothing created.`);
1681
+ else {
1682
+ print(`✓ tagged the final ${verdict.tag} on ${at} and pushed it to ${remote} — route deploy-tag-fast, by the operator's grant (decision #${verdict.grant.issue}); the release workflow deploys it in this run.`);
1683
+ if (published && published.ok) print(`✓ ${published.detail}`);
1684
+ else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --latest`);
1685
+ if (announced && announced.issues.length) print(`released in ${verdict.tag}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'}`);
1686
+ }
1687
+ } else if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
1551
1688
  else {
1552
1689
  print(`✓ cut ${verdict.tag} on ${at} and pushed it to ${remote} — a candidate, not a release; finalizing it is the release skill's.`);
1553
1690
  if (published && published.ok) print(`✓ ${published.detail}`);
@@ -1566,8 +1703,10 @@ function cmdReleaseCut(argv) {
1566
1703
  * workflow raced us) is left alone. Best-effort: the tag is already on origin, so a failure here is
1567
1704
  * reported, never a reason to undo the cut.
1568
1705
  */
1569
- function publishPrerelease(repoAbs, { tag, lastFinal, message }) {
1570
- if (!isGhUsable(repoAbs)) return { ok: false, detail: `pre-release NOT published: gh not usable (${ghUnusableWhy(repoAbs)})` };
1706
+ function publishPrerelease(repoAbs, { tag, lastFinal, message, final = false }) {
1707
+ // #446: a deploy-tag-fast final is published as a full release, marked latest.
1708
+ const kind = final ? 'release' : 'pre-release';
1709
+ if (!isGhUsable(repoAbs)) return { ok: false, detail: `${kind} NOT published: gh not usable (${ghUnusableWhy(repoAbs)})` };
1571
1710
  const view = spawnSync('gh', ['release', 'view', tag, '--json', 'tagName'], { cwd: repoAbs, encoding: 'utf8' });
1572
1711
  if (view.status === 0) return { ok: true, detail: `${tag} already has a GitHub Release — left as it is` };
1573
1712
  let notes;
@@ -1576,13 +1715,13 @@ function publishPrerelease(repoAbs, { tag, lastFinal, message }) {
1576
1715
  } catch (e) {
1577
1716
  notes = `## ${tag}\n\n(release notes unavailable: ${e.message})\n`;
1578
1717
  }
1579
- notes += `\n### Candidate record\n\n\`\`\`\n${message}\`\`\`\n`;
1718
+ notes += `\n### ${final ? 'Release' : 'Candidate'} record\n\n\`\`\`\n${message}\`\`\`\n`;
1580
1719
  const file = path.join(os.tmpdir(), `colab-release-notes-${process.pid}-${tag}.md`);
1581
1720
  fs.writeFileSync(file, notes);
1582
1721
  try {
1583
- const r = spawnSync('gh', releaseCut.prereleaseArgs(tag, file), { cwd: repoAbs, encoding: 'utf8' });
1584
- if (r.status !== 0) return { ok: false, detail: `pre-release NOT published: gh release create ${tag} failed (${(r.stderr || '').split('\n')[0] || r.status})` };
1585
- return { ok: true, detail: `published the GitHub pre-release ${tag}` };
1722
+ const r = spawnSync('gh', final ? releaseCut.finalReleaseArgs(tag, file) : releaseCut.prereleaseArgs(tag, file), { cwd: repoAbs, encoding: 'utf8' });
1723
+ if (r.status !== 0) return { ok: false, detail: `${kind} NOT published: gh release create ${tag} failed (${(r.stderr || '').split('\n')[0] || r.status})` };
1724
+ return { ok: true, detail: `published the GitHub ${kind} ${tag}` };
1586
1725
  } finally {
1587
1726
  try { fs.unlinkSync(file); } catch (_) { /* best-effort */ }
1588
1727
  }
@@ -1877,22 +2016,7 @@ function cmdReleaseFinalize(argv) {
1877
2016
  // #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
1878
2017
  // carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
1879
2018
  let announced = null;
1880
- const announceRelease = (version, sha) => {
1881
- const prev = releaseFinalize.previousFinal(tagNames, version);
1882
- if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
1883
- const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
1884
- if (!log.ok) { warn(`could not read ${prev}..${shortSha(sha)} — no issue told it was released in ${version}`); return { range: `${prev}..${version}`, issues: [], posted: [], skipped: [], detail: 'git log failed' }; }
1885
- const nums = releaseFinalize.carriedIssues(log.stdout.split('\0'), { exclude: records.map((r) => r.number) });
1886
- const posted = []; const skipped = [];
1887
- for (const n of nums) {
1888
- const view = git.ghIssueView(repoAbs, n, ['comments']);
1889
- if (!view) { skipped.push(n); continue; }
1890
- if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
1891
- const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
1892
- if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
1893
- }
1894
- return { range: `${prev}..${version}`, issues: nums, posted, skipped };
1895
- };
2019
+ const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
1896
2020
  if (!opts.dry) {
1897
2021
  if (verdict.state === 'finalized') {
1898
2022
  const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}`;
@@ -46,8 +46,22 @@
46
46
  * section carrying its measured cost (parseMigrationSection). Every signal is written into the tag
47
47
  * message, so the reason for the bump is recorded mechanically.
48
48
  *
49
- * Never a final tag. Finalizing a candidate is the release skill's (#339), and a final is a human
50
- * act on every row where a tag reaches production.
49
+ * Never a final tag — with ONE exception, `deploy-tag-fast` (#446): there the operator granted a
50
+ * final on every green trunk head, so `--auto` tags `vX.Y.Z` directly (no candidate, no test period)
51
+ * and the release workflow deploys it in the same run. That branch adds five checks, all in the
52
+ * same closed vocabulary:
53
+ *
54
+ * spacing --auto only — finals at least release.final-spacing apart; inside the window
55
+ * the run is a NO-OP, and the first run after it tags main's head
56
+ * already-final replaces already-candidate — a head already carrying a final is a NO-OP
57
+ * final-grant the operator's recorded decision still resolves (release-policy.js
58
+ * finalGrantVerdict — the #441 reader, unchanged)
59
+ * release-hold no open issue carries the human veto label
60
+ * migration-grant no migration since the last final unless the version's tracking issue is
61
+ * granted one — otherwise a refusal whose `handoff` names the human command
62
+ *
63
+ * Elsewhere finalizing a candidate is the release skill's (#339), and a final is a human act on
64
+ * every row where a tag reaches production.
51
65
  */
52
66
 
53
67
  const migrationPaths = require('./migration-paths');
@@ -64,11 +78,23 @@ const BUMPS = Object.freeze(['patch', 'minor']);
64
78
  const RELEASE_BRANCH = 'main';
65
79
 
66
80
  const CONDITIONS = Object.freeze([
67
- 'release-policy', 'cadence', 'promotion', 'prerelease-trigger', 'version', 'already-candidate',
81
+ 'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
68
82
  ...releaseTag.PRE_TAG_CONDITIONS,
69
83
  'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
84
+ 'final-grant', 'release-hold', 'migration-grant',
70
85
  ]);
71
86
 
87
+ /** #446: the conditions only route deploy-tag-fast reports. */
88
+ const FAST_CONDITIONS = Object.freeze(['spacing', 'already-final', 'final-grant', 'release-hold', 'migration-grant']);
89
+
90
+ /** #446: the label a human puts on an issue to veto a release — the same one release-finalize reads. */
91
+ const HOLD_LABEL = 'release-hold';
92
+
93
+ /** #446: is this policy the fast route, where `cut --auto` tags the final itself? */
94
+ function isFastRoute(policy) {
95
+ return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
96
+ }
97
+
72
98
  /** The file a major's migration section is read from, at the candidate commit (#422). */
73
99
  const MIGRATION_FILE = 'MIGRATION.md';
74
100
 
@@ -390,6 +416,45 @@ function cadenceVerdict({ candidates, perDay, now }) {
390
416
  return { ok: false, detail: `${recent.length} candidate(s) in the last 24h (${recent.map((c) => c.name).join(', ')}) — release.candidates-per-day caps at ${perDay} a day; the first run from ${nextAt} cuts main's head, never an older commit`, nextAt };
391
417
  }
392
418
 
419
+ // ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
420
+
421
+ /**
422
+ * Finals at least `spacingHours` apart. `finals` is [{ name, date }] for every final tag (tagger
423
+ * date) — a human's final counts as much as an automatic one. Returns { ok, detail, nextAt }; not ok
424
+ * is a NO-OP for the caller, never a refusal, so the first run after the window tags main's head.
425
+ */
426
+ function spacingVerdict({ finals, spacingHours, now }) {
427
+ if (!spacingHours) return { ok: true, detail: 'no final spacing on this route', nextAt: null };
428
+ const nowMs = Date.parse(now);
429
+ const dated = (finals || []).map((f) => ({ ...f, ms: Date.parse(f.date) }))
430
+ .filter((f) => !Number.isNaN(f.ms) && f.ms <= nowMs).sort((a, b) => a.ms - b.ms);
431
+ if (!dated.length) return { ok: true, detail: 'no earlier final to space from', nextAt: null };
432
+ const last = dated[dated.length - 1];
433
+ const nextMs = last.ms + spacingHours * 3600000;
434
+ if (nowMs >= nextMs) return { ok: true, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()}, spacing ${spacingHours}h`, nextAt: null };
435
+ const nextAt = new Date(nextMs).toISOString();
436
+ return { ok: false, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()} — release.final-spacing keeps finals ${spacingHours}h apart; the first run from ${nextAt} tags main's head`, nextAt };
437
+ }
438
+
439
+ /**
440
+ * The human veto, repo-wide: `issues` is the open-issue list (null = unread — never "no hold").
441
+ * Any open issue carrying `release-hold` holds the next final; the fast route has no candidate issue
442
+ * to put the label on, so a human may put it on any issue, and only a human removes it.
443
+ */
444
+ function holdsVerdict(issues) {
445
+ if (issues === null || issues === undefined) return { ok: false, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
446
+ const held = issues.filter((i) => i && (!i.state || String(i.state).toUpperCase() === 'OPEN')
447
+ && (i.labels || []).some((l) => (l && typeof l === 'object' ? l.name : l) === HOLD_LABEL)).map((i) => i.number);
448
+ return held.length
449
+ ? { ok: false, detail: `${HOLD_LABEL} on ${held.map((n) => `#${n}`).join(', ')} — a human veto; no final is tagged while it is present, and no command removes it` }
450
+ : { ok: true, detail: `no open issue carries ${HOLD_LABEL}` };
451
+ }
452
+
453
+ /** The command a human runs to let a migration ride an automatic final on the fast route. */
454
+ function migrationHandoff(tracking, version) {
455
+ return `COLAB_HUMAN=1 colab migration-grant ${tracking || '<tracking issue>'} --branch ${version}`;
456
+ }
457
+
393
458
  // ---- #443: the newest candidate names trunk's head -------------------------------------------
394
459
 
395
460
  /** Events that run DOWNSTREAM of the suite (the release workflow itself) — never part of "head is green". */
@@ -452,6 +517,28 @@ function prereleaseArgs(tag, notesFile) {
452
517
  return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--prerelease', '--latest=false'];
453
518
  }
454
519
 
520
+ /** #446: a deploy-tag-fast final's GitHub Release — a full release, marked latest. */
521
+ function finalReleaseArgs(tag, notesFile) {
522
+ return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--latest'];
523
+ }
524
+
525
+ /**
526
+ * #446: the tracking issue a fast-route migration hand-off opens. Same marker as release-finalize's
527
+ * (`<!-- colab:release version=… -->`), so every reader finds it; the text says what is owed here —
528
+ * a migration grant, not a candidate's test period.
529
+ */
530
+ function handoffTrackingBody(version) {
531
+ return [
532
+ `<!-- colab:release version=${version} -->`,
533
+ '',
534
+ `Release tracking record for **${version}** — opened by \`colab release cut --auto\` on route \`deploy-tag-fast\` (CONVENTIONS.md §6). A record, not a unit of work: never claimed, never started.`,
535
+ '',
536
+ '- The final is automatic on every green head, by the operator\'s grant — but a database migration since the last final never rides an automatic deploy ungranted.',
537
+ `- **To let it ride:** a human runs \`COLAB_HUMAN=1 colab migration-grant <this issue> --branch ${version}\`; the next green run tags and deploys ${version}.`,
538
+ `- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
539
+ ].join('\n') + '\n';
540
+ }
541
+
455
542
  // ---- §6 condition 2: the full suite ------------------------------------------------------------
456
543
 
457
544
  /**
@@ -709,9 +796,14 @@ function decide(facts) {
709
796
  const add = (condition, ok, detail) => checks.push({ condition, ok: !!ok, detail });
710
797
 
711
798
  const p = f.policy;
799
+ const fast = isFastRoute(p) && !(p.findings && p.findings.length);
712
800
  if (!p) add('release-policy', false, 'no release policy was evaluated');
713
801
  else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
714
- else if (p.effective.candidates !== 'auto') {
802
+ else if (fast && !f.auto) {
803
+ add('release-policy', false, 'route deploy-tag-fast tags its finals only from the release workflow (`colab release cut --auto`), where the deploy runs in the same run — a final cut by hand would reach production with no deploy job behind it');
804
+ } else if (fast) {
805
+ add('release-policy', true, `${p.derived.axis} (${p.derived.row}, route deploy-tag-fast): a final on every green head, granted by decision #${p.effective.finalGrant.issue}, health gate ${p.effective.healthGate.url} (rollback: ${p.effective.healthGate.rollback}), spacing ${p.effective.finalSpacingHours}h`);
806
+ } else if (p.effective.candidates !== 'auto') {
715
807
  const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
716
808
  add('release-policy', false, narrowed
717
809
  ? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
@@ -726,6 +818,11 @@ function decide(facts) {
726
818
  const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
727
819
  add('cadence', cad.ok, cad.detail);
728
820
  if (!cad.ok) noop = !!f.auto.cadence;
821
+ if (fast) {
822
+ const sp = f.auto.spacing || { ok: false, detail: 'final spacing not measured' };
823
+ add('spacing', sp.ok, sp.detail);
824
+ if (!sp.ok && f.auto.spacing) noop = true;
825
+ }
729
826
  // #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
730
827
  const pr = f.auto.promotion;
731
828
  if (pr) {
@@ -747,7 +844,16 @@ function decide(facts) {
747
844
 
748
845
  let tag = null;
749
846
  let derivable = [];
750
- if (v.ok) {
847
+ if (v.ok && fast) {
848
+ const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
849
+ if (finalHere.length) {
850
+ add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
851
+ if (f.auto) noop = true;
852
+ } else {
853
+ tag = v.version;
854
+ add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
855
+ }
856
+ } else if (v.ok) {
751
857
  const here = candidateNumbers(f.tagsAtSha || [], v.version);
752
858
  if (here.length) {
753
859
  add('already-candidate', false, `this commit is already ${v.version}-rc.${here[here.length - 1]} — a second candidate for the same commit tests nothing new`);
@@ -776,6 +882,20 @@ function decide(facts) {
776
882
  else add(condition, verdict.ok, verdict.detail);
777
883
  }
778
884
 
885
+ // #446: what the fast route keeps in place of the test period it does not have.
886
+ let handoff = null;
887
+ let grant = null;
888
+ if (fast) {
889
+ const g = f.finalGrant || { ok: false, detail: `release.final-grant #${p.effective.finalGrant.issue} was not resolved — an unresolved grant is not a grant` };
890
+ add('final-grant', g.ok, g.detail);
891
+ if (g.ok) grant = { issue: p.effective.finalGrant.issue, ruledBy: g.ruledBy || null };
892
+ const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
893
+ add('release-hold', h.ok, h.detail);
894
+ const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
895
+ add('migration-grant', mig.ok, mig.detail);
896
+ if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
897
+ }
898
+
779
899
  const refusals = checks.filter((c) => !c.ok);
780
900
  const ok = refusals.length === 0 && !!tag;
781
901
  return {
@@ -783,6 +903,8 @@ function decide(facts) {
783
903
  bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
784
904
  signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
785
905
  derivable,
906
+ final: fast, grant, handoff,
907
+ healthGate: fast ? p.effective.healthGate : null,
786
908
  };
787
909
  }
788
910
 
@@ -793,8 +915,11 @@ function versionSourceOf(policy) {
793
915
 
794
916
  /** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
795
917
  function tagMessage(verdict, { sha, lastFinal }) {
918
+ // #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
919
+ // reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
920
+ const fast = !!verdict.final;
796
921
  const lines = [
797
- `${verdict.tag} — release candidate (colab release cut)`,
922
+ fast ? `${verdict.tag} — release (colab release cut, deploy-tag-fast)` : `${verdict.tag} — release candidate (colab release cut)`,
798
923
  '',
799
924
  `Commit: ${sha}`,
800
925
  `Since: ${lastFinal}`,
@@ -802,21 +927,24 @@ function tagMessage(verdict, { sha, lastFinal }) {
802
927
  '',
803
928
  ...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
804
929
  ...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
930
+ ...(fast && verdict.grant ? [`Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or route: deploy-tag, revokes it)`] : []),
931
+ ...(fast && verdict.healthGate ? [`Health gate: ${verdict.healthGate.url} (rollback: ${verdict.healthGate.rollback}) — the release workflow deploys this tag in the same run and verifies it there`, ''] : []),
805
932
  ...(verdict.derivable && verdict.derivable.length ? [`Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
806
933
  'Conditions (CONVENTIONS.md §6):',
807
934
  ...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
808
935
  '',
809
- 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
936
+ fast ? 'A final with no candidate: route deploy-tag-fast, by the operator\'s grant (CONVENTIONS.md §6).' : 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
810
937
  ];
811
938
  return lines.join('\n') + '\n';
812
939
  }
813
940
 
814
941
  module.exports = {
815
- CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH,
942
+ CONDITIONS, FAST_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
943
+ isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
816
944
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
817
945
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
818
946
  fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
819
947
  parseSwitchMarkers, switchVerdict,
820
948
  promotionVerdict, decide, tagMessage, versionSourceOf,
821
- DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs,
949
+ DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
822
950
  };
@@ -397,6 +397,13 @@ function decide(facts) {
397
397
  else if (!/^released-/.test(row)) add('release-policy', false, `${p.derived.axis}: ${p.derived.why} — nothing to finalize here (CONVENTIONS.md §6, The release rung)`);
398
398
  else add('release-policy', true, `${p.derived.axis} (${row}): final ${finalMode}, test period ${p.effective.testPeriodDays}d`);
399
399
  if (!checks[0].ok) return out('refused');
400
+ // #446: route deploy-tag-fast tags its finals in `release cut --auto`, with no candidate. A leftover
401
+ // candidate from an earlier route is superseded by the next final — never finalized here, where the
402
+ // grant would otherwise finalize an old -rc days after the operator chose the fast route.
403
+ if (p.effective.finalize === 'on-green-head') {
404
+ add('candidate', false, 'route deploy-tag-fast cuts its finals in `colab release cut --auto` on every green head — there is no candidate to finalize; one left over from an earlier route is superseded by the next final');
405
+ return out('no-candidate');
406
+ }
400
407
 
401
408
  const s = f.selection || { kind: 'none', detail: 'no candidate selected' };
402
409
  if (s.kind === 'none') { add('candidate', false, s.detail); return out('no-candidate'); }
@@ -8,7 +8,7 @@
8
8
  * declare to CHOOSE a route its row permits and to NARROW it:
9
9
  *
10
10
  * release:
11
- * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | live
11
+ * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
12
12
  * candidates: auto # auto | off
13
13
  * candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
14
14
  * test-period: 3d # <N>d, never below the route's 3 days
@@ -20,6 +20,9 @@
20
20
  * npm-gate: <command> # #433 — the pack-allowlist gate, run before every npm publish
21
21
  * version-source: tag # #438 — tag | manifest: is a manifest's version checked, or derivable?
22
22
  * final-grant: 123 # #441 — an operator's recorded decision letting deploy-tag's final be automatic
23
+ * health-url: https://… # #446 — deploy-tag-fast only: the public endpoint reporting the running version
24
+ * rollback: auto # #446 — deploy-tag-fast only: the deploy rolls itself back when that check fails
25
+ * final-spacing: 1h # #446 — deploy-tag-fast only: minimum time between finals (<N>h | <N>d, ≥ 1h)
23
26
  *
24
27
  * Two layers. The descriptor's ROW (exposure + deploy + production) is a fact about the repo; the
25
28
  * ROUTE is how releases run on it. A row permits a fixed set of routes (ROW_ROUTES) and derives one
@@ -44,7 +47,7 @@
44
47
 
45
48
  const axisAuthority = require('./axis-authority.js');
46
49
 
47
- const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant']);
50
+ const KEYS = Object.freeze(['route', 'candidates', 'candidates-per-day', 'test-period', 'final', 'guard-run', 'guard-result', 'exports', 'npm', 'npm-gate', 'version-source', 'final-grant', 'health-url', 'rollback', 'final-spacing']);
48
51
  // #438: where the version a tag names comes from. `manifest` (the default) — every declared manifest
49
52
  // (VERSION, package.json, Cargo.toml, pyproject.toml) must already equal the tag, so a human bumps it
50
53
  // on trunk first. `tag` — the tag is the version and the manifests are DERIVABLE: the pre-tag check
@@ -56,6 +59,18 @@ const VERSION_SOURCES = Object.freeze(['manifest', 'tag']);
56
59
  // sit on — `deploy: tag` only. `deploy: manual` stays human: a person runs that deploy anyway.
57
60
  const GRANTABLE_ROUTE = 'deploy-tag';
58
61
  const GRANTABLE_ROW = 'released-tag';
62
+ // #446: the route that cuts a FINAL on every green trunk head — no candidate, no test period — and
63
+ // deploys it in the same run. It exists only on deploy: tag, only with the operator's recorded grant
64
+ // (the #441 reader, unchanged), and only where the repo declares a health-gated deploy that rolls
65
+ // itself back: those two declarations stand in for the test period it does not have. Its own keys —
66
+ // `health-url`, `rollback`, `final-spacing` — fit this route alone.
67
+ const FAST_ROUTE = 'deploy-tag-fast';
68
+ const GRANTABLE_ROUTES = Object.freeze([GRANTABLE_ROUTE, FAST_ROUTE]);
69
+ const FAST_KEYS = Object.freeze(['health-url', 'rollback', 'final-spacing']);
70
+ const ROLLBACK = Object.freeze(['auto']);
71
+ // The minimum spacing between two finals on deploy-tag-fast: both the default and the floor. A burst
72
+ // of merges then deploys at most once an hour; a repo may lengthen it, never shorten it.
73
+ const FINAL_SPACING_HOURS = 1;
59
74
  // #433: the npm opt-in. `npm` names the package directory release-auto.yml publishes (`.` for the
60
75
  // root); `npm-gate` the command that proves the tarball holds only what was meant to ship. They are
61
76
  // a pair — a publish with no gate is the stray-local-file leak the gate exists to stop — and they
@@ -84,7 +99,8 @@ const TEST_PERIOD_DAYS = 3;
84
99
  * finalize how a final is reached: 'none' (no tags), 'after-test-period' (each clean
85
100
  * candidate on its own clock), 'newest-clean' (the newest candidate clean for
86
101
  * the period; a newer candidate does not restart an older one's clock),
87
- * 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click'.
102
+ * 'on-tag' (the tag itself triggers the publish; no candidate), 'human-click',
103
+ * 'on-green-head' (#446: `release cut --auto` tags the final itself; no candidate).
88
104
  */
89
105
  const ROUTE_POLICY = Object.freeze({
90
106
  'none': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'nothing consumes a tag here, so no tags are cut' }),
@@ -92,6 +108,7 @@ const ROUTE_POLICY = Object.freeze({
92
108
  'public-tool': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'auto', finalize: 'after-test-period', why: 'adopters install it and nothing deploys: every green trunk head gets a candidate, and the final tag is automatic after a clean test period' }),
93
109
  'library-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-tag', why: 'a library released per merge and pinned by its consumers: no candidates, the tag triggers the publish and the route\'s checks still apply' }),
94
110
  'deploy-tag': Object.freeze({ candidates: 'auto', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'human-click', why: 'the tag deploys production, so the final tag is a human act' }),
111
+ 'deploy-tag-fast': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: null, final: 'auto', finalize: 'on-green-head', why: 'the operator granted a final on every green trunk head, deployed in the same run behind a health-gated deploy that rolls itself back' }),
95
112
  'live': Object.freeze({ candidates: 'off', candidatesPerDay: null, testPeriodDays: TEST_PERIOD_DAYS, final: 'human', finalize: 'none', why: 'the promotion is the deploy and stays human; no automatic tags' }),
96
113
  });
97
114
  const ROUTES = Object.freeze(Object.keys(ROUTE_POLICY));
@@ -105,7 +122,7 @@ const ROW_ROUTES = Object.freeze({
105
122
  'no-tags': Object.freeze(['none']),
106
123
  'live': Object.freeze(['live', 'none']),
107
124
  'released-no-production': Object.freeze(['public-tool', 'rapid-app', 'library-fast', 'none']),
108
- 'released-tag': Object.freeze(['deploy-tag', 'none']),
125
+ 'released-tag': Object.freeze(['deploy-tag', 'deploy-tag-fast', 'none']),
109
126
  'released-manual': Object.freeze(['deploy-tag', 'none']),
110
127
  'unmatched': Object.freeze(['none']),
111
128
  });
@@ -151,7 +168,35 @@ function deriveDefault(cfg) {
151
168
  /** A route's policy as an effective-shaped object (no `why`). */
152
169
  function routePolicy(route) {
153
170
  const p = ROUTE_POLICY[route];
154
- return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null } : null;
171
+ return p ? { route, candidates: p.candidates, candidatesPerDay: p.candidatesPerDay, testPeriodDays: p.testPeriodDays, final: p.final, finalize: p.finalize, npm: null, versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null } : null;
172
+ }
173
+
174
+ /** `6h` -> 6, `2d` -> 48; anything else (including `30m`, `0h`) -> null. */
175
+ function parseSpacing(v) {
176
+ const m = typeof v === 'string' ? /^([0-9]+)([hd])$/.exec(v.trim()) : null;
177
+ if (!m) return null;
178
+ const n = parseInt(m[1], 10) * (m[2] === 'd' ? 24 : 1);
179
+ return n > 0 ? n : null;
180
+ }
181
+
182
+ /** A health URL is an absolute https:// URL with a host. */
183
+ function validHealthUrl(v) {
184
+ if (typeof v !== 'string' || !/^https:\/\/[^\s/]+/.test(v.trim())) return false;
185
+ try { return new URL(v.trim()).protocol === 'https:'; } catch { return false; }
186
+ }
187
+
188
+ /**
189
+ * #446: what a declared `deploy-tag-fast` still lacks — the operator's grant, the health URL, the
190
+ * rollback declaration. Empty array = all three present (shape only; the grant's tracker state is
191
+ * finalGrantVerdict's).
192
+ */
193
+ function fastRoutePrerequisites(raw) {
194
+ const r = raw || {};
195
+ const missing = [];
196
+ if (parseGrantIssue(r['final-grant']) === null) missing.push("release.final-grant: <N> — the operator's recorded decision (colab decision <N> --record --ruled-by <human>)");
197
+ if (!validHealthUrl(r['health-url'])) missing.push('release.health-url: https://… — the public endpoint that reports the running version');
198
+ if (!ROLLBACK.includes(r.rollback)) missing.push('release.rollback: auto — the deploy rolls itself back when the health check fails');
199
+ return missing;
155
200
  }
156
201
 
157
202
  function parseTestPeriod(v) {
@@ -176,7 +221,7 @@ function evaluateRelease(cfg) {
176
221
  const fromDerived = () => ({
177
222
  route: derived.route, candidates: derived.candidates, candidatesPerDay: derived.candidatesPerDay,
178
223
  testPeriodDays: derived.testPeriodDays, final: derived.final, finalize: derived.finalize, npm: null,
179
- versionSource: 'manifest', finalGrant: null,
224
+ versionSource: 'manifest', finalGrant: null, healthGate: null, finalSpacingHours: null,
180
225
  });
181
226
  let effective = fromDerived();
182
227
  const findings = [];
@@ -222,6 +267,11 @@ function evaluateRelease(cfg) {
222
267
  else if (!allowed.includes(v)) {
223
268
  fail(`release.route: ${v} does not fit ${derived.axis} — that descriptor permits ${allowed.join(' or ')} (${routes}). ` +
224
269
  'A route is chosen among the ones exposure + deploy permit; change those first if the repo really changed');
270
+ } else if (v === FAST_ROUTE && fastRoutePrerequisites(raw).length) {
271
+ // Fail closed: without its grant and its health gate the fast route would be an automatic,
272
+ // untested deploy nobody chose. The derived route (deploy-tag, human final) stays in effect.
273
+ fail(`release.route: ${FAST_ROUTE} needs the operator's grant and a declared health-gated deploy before it may stand — missing: ` +
274
+ `${fastRoutePrerequisites(raw).join('; ')} (${routes}). Until then the final stays a human act on route ${derived.route}`);
225
275
  } else {
226
276
  effective = routePolicy(v);
227
277
  why = ROUTE_POLICY[v].why;
@@ -259,8 +309,14 @@ function evaluateRelease(cfg) {
259
309
  if ('final-grant' in raw) {
260
310
  const n = parseGrantIssue(raw['final-grant']);
261
311
  if (n === null) fail(`release.final-grant is ${JSON.stringify(raw['final-grant'])}, expected the number of the decision issue that records the operator's ruling (e.g. 123 or "#123")`);
262
- else if (effective.route !== GRANTABLE_ROUTE || derived.row !== GRANTABLE_ROW) {
263
- fail(`release.final-grant fits only route ${GRANTABLE_ROUTE} on deploy: tag — ${route} on ${derived.axis} is not that (${routes}). ` +
312
+ else if (effective.route === FAST_ROUTE) {
313
+ // #446: the route itself is the automatic final, so the grant takes effect from this line alone.
314
+ grant = { issue: n };
315
+ effective.finalGrant = grant;
316
+ } else if (raw.route === FAST_ROUTE) {
317
+ // The route was refused above; its grant line is not a second finding.
318
+ } else if (effective.route !== GRANTABLE_ROUTE || derived.row !== GRANTABLE_ROW) {
319
+ fail(`release.final-grant fits only route ${GRANTABLE_ROUTE} on deploy: tag (or ${FAST_ROUTE}) — ${route} on ${derived.axis} is not that (${routes}). ` +
264
320
  (derived.row === 'released-manual' ? 'On deploy: manual a person runs the deploy anyway, so its final stays human' : 'Its final is not a deploying human act, so there is nothing to grant'));
265
321
  } else grant = { issue: n };
266
322
  }
@@ -268,7 +324,9 @@ function evaluateRelease(cfg) {
268
324
  if ('final' in raw) {
269
325
  const v = raw.final;
270
326
  if (!FINAL.includes(v)) fail(`release.final is ${JSON.stringify(v)}, expected "auto" or "human"`);
271
- else if (v === 'auto' && effective.final === 'human' && grant) {
327
+ else if (effective.route === FAST_ROUTE) {
328
+ if (v === 'human') fail(`release.final: human on route ${FAST_ROUTE} — that route has no candidate for a human to finalize; use route deploy-tag for a human final`);
329
+ } else if (v === 'auto' && effective.final === 'human' && grant) {
272
330
  // #441: an automatic final that deploys production — permitted only by the recorded grant.
273
331
  effective.final = 'auto';
274
332
  effective.finalize = 'after-test-period';
@@ -288,7 +346,7 @@ function evaluateRelease(cfg) {
288
346
  const v = raw['test-period'];
289
347
  const days = parseTestPeriod(v);
290
348
  if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
291
- else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} finalizes on the tag itself, with no candidate. Remove the key`);
349
+ else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
292
350
  else if (days < effective.testPeriodDays) {
293
351
  widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer`);
294
352
  } else effective.testPeriodDays = days;
@@ -301,6 +359,21 @@ function evaluateRelease(cfg) {
301
359
  else effective.versionSource = v;
302
360
  }
303
361
 
362
+ // #446: the fast route's own keys — only there, and the floor on spacing.
363
+ const fastKeys = FAST_KEYS.filter((k) => k in raw);
364
+ if (effective.route === FAST_ROUTE) {
365
+ effective.healthGate = { url: raw['health-url'].trim(), rollback: raw.rollback };
366
+ effective.finalSpacingHours = FINAL_SPACING_HOURS;
367
+ if ('final-spacing' in raw) {
368
+ const h = parseSpacing(raw['final-spacing']);
369
+ if (h === null) fail(`release.final-spacing is ${JSON.stringify(raw['final-spacing'])}, expected hours or days like "${FINAL_SPACING_HOURS}h" or "1d"`);
370
+ else if (h < FINAL_SPACING_HOURS) widen('final-spacing', raw['final-spacing'], `finals are at least ${FINAL_SPACING_HOURS}h apart. Set ${FINAL_SPACING_HOURS}h or longer`);
371
+ else effective.finalSpacingHours = h;
372
+ }
373
+ } else if (fastKeys.length && raw.route !== FAST_ROUTE) {
374
+ fail(`release.${fastKeys.join(' / release.')} fits only route ${FAST_ROUTE} — ${route} on ${derived.axis} is not that (${routes}). Remove the key${fastKeys.length > 1 ? 's' : ''}`);
375
+ }
376
+
304
377
  // 3. npm (#433) — only on a route where a tag publishes to adopters and deploys nothing.
305
378
  effective.npm = null;
306
379
  if ('npm' in raw || 'npm-gate' in raw) {
@@ -352,7 +425,8 @@ function finalGrantVerdict(record, { issue, trust } = {}) {
352
425
  }
353
426
 
354
427
  module.exports = {
355
- VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, parseGrantIssue, finalGrantVerdict,
428
+ VERSION_SOURCES, GRANTABLE_ROUTE, GRANTABLE_ROW, GRANTABLE_ROUTES, FAST_ROUTE, FAST_KEYS, ROLLBACK, FINAL_SPACING_HOURS,
429
+ parseGrantIssue, finalGrantVerdict, parseSpacing, validHealthUrl, fastRoutePrerequisites,
356
430
  KEYS, INPUT_KEYS, NPM_KEYS, NPM_ROUTES, CANDIDATES, FINAL, TEST_PERIOD_DAYS, ROUTES, ROUTE_POLICY, ROW_ROUTES,
357
431
  deriveDefault, evaluateRelease, parseTestPeriod, routePolicy,
358
432
  };