@futurelastic/colab-handbook 1.14.0-rc.4 → 1.14.0-rc.6

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.4"
36
+ "version": "1.14.0-rc.6"
37
37
  }
@@ -29,11 +29,14 @@
29
29
  # comment above that job
30
30
  # the cut tagged a FINAL — route deploy + health check (job `deploy`, #446) — see
31
31
  # deploy-tag-fast only "DEPLOYING IN THIS RUN" below
32
+ # the cut tagged a FINAL — route published like any tag (Release marked latest, npm
33
+ # library-fast (#590) `latest`); nothing deploys — see "A LIBRARY" below
32
34
  #
33
35
  # Every decision — whether a candidate is owed, which bump, whether the test period
34
36
  # elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
35
37
  # read from .github/project.yml's release rung. This file only schedules it and publishes
36
- # what it tagged. Where the rung leaves candidates off, every run is a recorded refusal.
38
+ # what it tagged. Where the rung leaves candidates off, every run is a recorded refusal — save on
39
+ # route library-fast, where the cut is the final (below).
37
40
  #
38
41
  # WHERE IT FITS. `colab release cut` tags origin/main — release tags land on `main` on every
39
42
  # trunk shape — so the same file, unchanged, fits two kinds of repo:
@@ -94,6 +97,14 @@
94
97
  # run still concludes on the `release` job. EDIT: on this route, a cron more frequent than daily
95
98
  # tags a head that release.final-spacing held back sooner.
96
99
  #
100
+ # A LIBRARY — THE CUT IS THE FINAL (library-fast, #590). On a repo with no production that declares
101
+ # `release.route: library-fast`, `colab release cut --auto` tags the FINAL vX.Y.Z on a green main
102
+ # head once a first final exists (the first is a human's tag) — no candidate, no test period. With
103
+ # `release.version-source: manifest` (the route's default) the version is the manifest's: a merge
104
+ # that bumps package.json releases it, a merge that does not is a no-op. This run publishes the
105
+ # final itself — the Release step marks it latest, the npm job publishes it to `latest` — because a
106
+ # publish-on-tag workflow would not fire for a tag this job pushes. The deploy job stays skipped.
107
+ #
97
108
  # DRY RUN ON A FIX BRANCH (#474). This workflow never runs on a branch by itself, so a fix to it
98
109
  # (a moved runner label, a HANDBOOK_REF naming a missing branch) had no run to prove it, and the
99
110
  # cure rule (CONVENTIONS.md §4) could only refuse it — a human ci-grant was the one door. Dispatch
@@ -475,8 +486,10 @@ jobs:
475
486
  echo "tag=$TAG" >> "$GITHUB_OUTPUT"
476
487
  echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
477
488
  # #446: on route deploy-tag-fast the cut IS the final, and the deploy job deploys it in
478
- # this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow).
479
- if [ "$(jq -r '.final // false' "$OUT")" = "true" ]; then
489
+ # this run (a tag pushed with GITHUB_TOKEN starts no `push: tags` workflow). #590: route
490
+ # library-fast cuts a final too, with `deploy: null` — it is published below (Release, npm)
491
+ # and never handed to the deploy job, so key on the deploy facts, not on `final`.
492
+ if [ "$(jq -r '.final == true and .deploy != null' "$OUT")" = "true" ]; then
480
493
  echo "final=$TAG" >> "$GITHUB_OUTPUT"
481
494
  echo "health-url=$(jq -r '.deploy.healthUrl // ""' "$OUT")" >> "$GITHUB_OUTPUT"
482
495
  fi
package/tools/colab CHANGED
@@ -1335,6 +1335,18 @@ Refuses, naming each failed condition (all are reported, not just the first):
1335
1335
  There the bump reads the promoted commits (main's merge subject is skipped),
1336
1336
  and a switch-removal child counts when its Closes #N was promoted.
1337
1337
 
1338
+ Route library-fast (#590) — a library released per merge, its consumers pin; nothing deploys:
1339
+ once a first final exists (a human tags it), cut tags the next FINAL vX.Y.Z directly — no
1340
+ candidate, no test period — by hand or with --auto, publishes it as the latest GitHub Release and
1341
+ moves the stable channel. --json says final: true, deploy: null. In place of already-candidate:
1342
+ already-final main's head already carries a final — a NO-OP under --auto
1343
+ release-hold an open issue carries the release-hold label (a human veto)
1344
+ With release.version-source: manifest (the route's default) the version IS the manifest's: equal
1345
+ to the last final is a NO-OP (nothing to release until a merge bumps it), lower refuses, 0.x -> 1.0
1346
+ refuses (a human tags it), a major needs MIGRATION.md's section, and a breaking change the
1347
+ manifest under-declares refuses. --bump has nothing to override there. With version-source: tag
1348
+ the bump is computed exactly as for a candidate.
1349
+
1338
1350
  Route deploy-tag-fast (#446) — a deploy: tag repo with the operator's grant and a declared health gate:
1339
1351
  --auto tags the FINAL vX.Y.Z on main's green head — no candidate, no test period — publishes it as
1340
1352
  the latest GitHub Release, moves the stable channel, and prints final/deploy in --json so the
@@ -1682,11 +1694,23 @@ function cmdReleaseCut(argv) {
1682
1694
  const fast = releaseCut.isFastRoute(policy) && !policy.findings.length;
1683
1695
  const fastFacts = fast ? measureFastRoute(repoAbs, { policy, remote, issues, lastFinal, tags, auto, migrationPaths: migrationPathsSince }) : {};
1684
1696
  if (fast && auto) auto.spacing = fastFacts.spacing;
1697
+ // #590: route library-fast — a final with nothing deployed. The release-hold veto is its one extra
1698
+ // read; a hand cut also needs MIGRATION.md for a manifest-declared major (--auto reads it already).
1699
+ const library = !fast && releaseCut.isLibraryRoute(policy) && !policy.findings.length;
1700
+ let libraryMigration = null;
1701
+ if (library) {
1702
+ fastFacts.holds = releaseCut.holdsVerdict(issues);
1703
+ if (!auto) {
1704
+ const r = git.git(['show', `${sha}:${releaseCut.MIGRATION_FILE}`], repoAbs);
1705
+ const text = r.ok ? r.stdout : null;
1706
+ libraryMigration = (v) => releaseCut.parseMigrationSection(text, v);
1707
+ }
1708
+ }
1685
1709
 
1686
1710
  const verdict = releaseCut.decide({
1687
1711
  policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
1688
1712
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1689
- finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations,
1713
+ finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1690
1714
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
1691
1715
  });
1692
1716
 
@@ -1716,6 +1740,11 @@ function cmdReleaseCut(argv) {
1716
1740
  // on the version's tracking issue (opened if there is none), for a human to grant.
1717
1741
  let announced = null;
1718
1742
  let handoff = verdict.handoff || null;
1743
+ if (library && !opts.dry && created) {
1744
+ // #590: every issue a library final carries hears which version has it, as on deploy-tag-fast.
1745
+ const exclude = (issues || []).filter((i) => releaseFinalize.parseReleaseMarker(i.body)).map((i) => i.number);
1746
+ announced = announceCarried(repoAbs, { tagNames: [...tags, verdict.tag], exclude, version: verdict.tag, sha });
1747
+ }
1719
1748
  if (fast && !opts.dry) {
1720
1749
  if (created) {
1721
1750
  const exclude = (issues || []).filter((i) => releaseFinalize.parseReleaseMarker(i.body)).map((i) => i.number);
@@ -1745,10 +1774,11 @@ function cmdReleaseCut(argv) {
1745
1774
  repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1746
1775
  ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1747
1776
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1748
- // #446: present on every route, so the workflow reads one shape — final only on deploy-tag-fast.
1749
- final: !!verdict.final,
1777
+ // #446: present on every route, so the workflow reads one shape — final on deploy-tag-fast and
1778
+ // library-fast (#590); deploy only on deploy-tag-fast, so the workflow deploys nothing a library tags.
1779
+ final: !!verdict.final, route: verdict.route || null,
1750
1780
  deploy: verdict.final && verdict.healthGate ? { healthUrl: verdict.healthGate.url, rollback: verdict.healthGate.rollback } : null,
1751
- grant: verdict.grant || null, handoff, ...(fast ? { announced } : {}),
1781
+ grant: verdict.grant || null, handoff, ...(fast || library ? { announced } : {}),
1752
1782
  }, null, 2));
1753
1783
  return verdict.ok || verdict.noop ? 0 : 1;
1754
1784
  }
@@ -1764,6 +1794,8 @@ function cmdReleaseCut(argv) {
1764
1794
  if (verdict.noop) {
1765
1795
  print(fast
1766
1796
  ? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
1797
+ : library
1798
+ ? '· no-op — nothing owed (the manifest still says the last final), or main\'s head already carries a final; nothing tagged.'
1767
1799
  : '· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
1768
1800
  return 0;
1769
1801
  }
@@ -1774,7 +1806,15 @@ function cmdReleaseCut(argv) {
1774
1806
  if (handoff) print(`\nA migration rides this release. The one command, for a human to run:\n ${handoff}`);
1775
1807
  return 1;
1776
1808
  }
1777
- if (verdict.final) {
1809
+ if (verdict.final && library) {
1810
+ 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 — route library-fast, nothing deploys. Nothing created.`);
1811
+ else {
1812
+ print(`✓ tagged the final ${verdict.tag} on ${at} and pushed it to ${remote} — route library-fast: a library released per merge, nothing deploys from it.`);
1813
+ if (published && published.ok) print(`✓ ${published.detail}`);
1814
+ else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --latest`);
1815
+ if (announced && announced.issues.length) print(`released in ${verdict.tag}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'}`);
1816
+ }
1817
+ } else if (verdict.final) {
1778
1818
  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.`);
1779
1819
  else {
1780
1820
  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.`);
@@ -46,7 +46,7 @@
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 — with ONE exception, `deploy-tag-fast` (#446): there the operator granted a
49
+ * Never a final tag — with two exceptions, `library-fast` (#590, below) and `deploy-tag-fast` (#446): on the latter the operator granted a
50
50
  * final on every green trunk head, so `--auto` tags `vX.Y.Z` directly (no candidate, no test period)
51
51
  * and the release workflow deploys it in the same run. That branch adds five checks, all in the
52
52
  * same closed vocabulary:
@@ -60,6 +60,14 @@
60
60
  * migration-grant no migration since the last final unless the version's tracking issue is
61
61
  * granted one — otherwise a refusal whose `handoff` names the human command
62
62
  *
63
+ * #590: route `library-fast` is the second final route — a library released per merge, nothing
64
+ * deployed. `cut` (by hand or `--auto`) tags `vX.Y.Z` directly once a first final exists, with
65
+ * `already-final` in place of `already-candidate` and the `release-hold` veto, and none of the fast
66
+ * route's grant, spacing, migration hand-off or health gate. Its version on `version-source:
67
+ * manifest` is the manifest's (decideManifestVersion): equal to the last final is a NO-OP, a break the
68
+ * manifest under-declares is a refusal; on `version-source: tag` the bump is computed as for a
69
+ * candidate.
70
+ *
63
71
  * Elsewhere finalizing a candidate is the release skill's (#339), and a final is a human act on
64
72
  * every row where a tag reaches production.
65
73
  */
@@ -110,6 +118,25 @@ function isFastRoute(policy) {
110
118
  return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
111
119
  }
112
120
 
121
+ /**
122
+ * #590: is this policy route library-fast as declared — no candidates, an automatic final reached
123
+ * by the tag itself? There `cut` tags the FINAL directly, as on deploy-tag-fast, but nothing deploys:
124
+ * no grant, no spacing, no migration hand-off, no health gate. A `final: human` narrowing keeps
125
+ * `finalize: on-tag` but makes every final a human act, so it is not this.
126
+ */
127
+ function isLibraryRoute(policy) {
128
+ const e = policy && policy.effective;
129
+ return !!(e && e.finalize === 'on-tag' && e.final === 'auto' && e.candidates === 'off');
130
+ }
131
+
132
+ /** #590: the route a refusal names — the one in effect, never the derived default it replaced. */
133
+ function routeWhy(policy) {
134
+ const releasePolicy = require('./release-policy');
135
+ const route = policy && policy.effective && policy.effective.route;
136
+ const own = route && releasePolicy.ROUTE_POLICY[route];
137
+ return { route, why: own ? own.why : policy.derived.why };
138
+ }
139
+
113
140
  /** The file a major's migration section is read from, at the candidate commit (#422). */
114
141
  const MIGRATION_FILE = 'MIGRATION.md';
115
142
 
@@ -413,6 +440,63 @@ function decideAutoVersion({ lastFinal, signals, migration, tags }) {
413
440
  return { ok: true, detail: `${lastFinal} -> ${version} (${bump}, computed: ${why})`, version, bump, why, overridden: null, migration: mig };
414
441
  }
415
442
 
443
+ // ---- #590: library-fast — the version the manifest already says ------------------------------
444
+
445
+ /**
446
+ * Route library-fast with `release.version-source: manifest`: the release is the version a merge
447
+ * already put in the manifest, so the cut computes no bump — it checks the manifest's.
448
+ * manifests release-tag.js manifestVersions() at the commit (null = unread)
449
+ * breaking [why] — a breaking signal since the last final (autoSignals' `breaking`, or the
450
+ * manual cut's semverSuggestion when it says major); empty when none
451
+ * migration (version) => parseMigrationSection result, asked only for a major
452
+ * Returns decideVersion's shape, plus `nothing` (the manifest still says the last final — a no-op
453
+ * under --auto) and `fallback` (no manifest declares a version: the caller computes the bump as on
454
+ * version-source: tag).
455
+ */
456
+ function decideManifestVersion({ lastFinal, manifests, tags, breaking, migration }) {
457
+ const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
458
+ if (!lastFinal) return refuse('no final release tag (vX.Y.Z) on main yet — the first version is a human decision, not a computed bump');
459
+ const last = parseVersion(lastFinal);
460
+ if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compare the manifest against it`);
461
+ if (manifests === null || manifests === undefined) return refuse('the manifests could not be read at the commit — an unread version is not a release', { unread: true });
462
+ const bad = manifests.filter((m) => m.error).map((m) => `${m.file}: ${m.error}`);
463
+ if (bad.length) return refuse(`a manifest does not read — ${bad.join('; ')}`);
464
+ const stated = manifests.filter((m) => !m.dynamic && m.version !== undefined && m.version !== null);
465
+ if (!stated.length) return { ok: false, fallback: true, detail: 'no manifest states a version' };
466
+ const values = [...new Set(stated.map((m) => String(m.version).replace(/^v/, '')))];
467
+ if (values.length > 1) return refuse(`the manifests disagree on the version — ${stated.map((m) => `${m.file} says ${m.version}`).join('; ')}`);
468
+ const v = parseVersion(`v${values[0]}`);
469
+ const where = stated.map((m) => m.file).join(', ');
470
+ if (!v) return refuse(`${where} says ${values[0]}, which is not X.Y.Z — route library-fast tags finals only, never a pre-release`);
471
+ const version = formatVersion(v);
472
+ const cmp = (a, b) => (a.major - b.major) || (a.minor - b.minor) || (a.patch - b.patch);
473
+ if (cmp(v, last) === 0) {
474
+ return refuse(`${where} still says ${values[0]}, the last final ${lastFinal} — nothing to release until a merge bumps it (route library-fast, release.version-source: manifest)`, { nothing: true });
475
+ }
476
+ if (cmp(v, last) < 0) return refuse(`${where} says ${values[0]}, below the last final ${lastFinal} — the manifest moved backwards`);
477
+ if ((tags || []).includes(version)) return refuse(`${version} is already a final tag`);
478
+
479
+ const bump = v.major !== last.major ? 'major' : v.minor !== last.minor ? 'minor' : 'patch';
480
+ const brk = breaking || [];
481
+ let mig = null;
482
+ if (bump === 'major') {
483
+ if (last.major === 0) {
484
+ return refuse(`${where} says ${values[0]} — the step from 0.x to ${version} is a human decision (CONVENTIONS.md §6, Versioning): tag it by hand, and later finals follow the manifest`, { bump });
485
+ }
486
+ mig = typeof migration === 'function' ? migration(version) : (migration || null);
487
+ if (!mig || !mig.ok) {
488
+ return refuse(`${lastFinal} -> ${version} is a major, refused: ${mig ? mig.detail : `no migration section read for ${version}`}`, { bump, migration: mig });
489
+ }
490
+ } else if (brk.length) {
491
+ const owed = last.major === 0 ? 'minor' : 'major';
492
+ if (owed === 'major' || bump === 'patch') {
493
+ return refuse(`a breaking change since ${lastFinal} (${brk.join('; ')}) but ${where} only bumps to ${values[0]} (a ${bump}) — a break needs a ${owed}. Bump the manifest on trunk, or show the change is not breaking`, { bump });
494
+ }
495
+ }
496
+ const why = `${where} says ${values[0]}${brk.length ? ` (breaking since ${lastFinal}: ${brk.join('; ')})` : ''}`;
497
+ return { ok: true, detail: `${lastFinal} -> ${version} (${bump}, from the manifest: ${why})`, version, bump, why, overridden: null, migration: mig };
498
+ }
499
+
416
500
  // ---- --auto: cadence (#422) ------------------------------------------------------------------
417
501
 
418
502
  /**
@@ -866,17 +950,26 @@ function decide(facts) {
866
950
 
867
951
  const p = f.policy;
868
952
  const fast = isFastRoute(p) && !(p.findings && p.findings.length);
953
+ // #590: route library-fast — a final with no candidate, like the fast route, and nothing deployed.
954
+ const library = !fast && isLibraryRoute(p) && !(p.findings && p.findings.length);
955
+ const finalRoute = fast || library;
869
956
  if (!p) add('release-policy', false, 'no release policy was evaluated', true);
870
957
  else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
871
958
  else if (fast && !f.auto) {
872
959
  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');
873
960
  } else if (fast) {
874
961
  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`);
962
+ } else if (library) {
963
+ add('release-policy', true, `${p.derived.axis} (${p.derived.row}, route library-fast): a final on every release the version source owes — no candidate, nothing deployed (version source: ${versionSourceOf(p)})`);
875
964
  } else if (p.effective.candidates !== 'auto') {
876
965
  const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
966
+ const { route, why } = routeWhy(p);
967
+ const humanFinal = route === 'library-fast' && p.effective.final === 'human';
877
968
  add('release-policy', false, narrowed
878
969
  ? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
879
- : `candidates are off on ${p.derived.axis}: ${p.derived.why} (CONVENTIONS.md §6, The release rung)`);
970
+ : humanFinal
971
+ ? `route library-fast with release.final: human — every final here is a human act: tag vX.Y.Z by hand (CONVENTIONS.md §6, The release rung)`
972
+ : `candidates are off on ${p.derived.axis}${route ? `, route ${route}` : ''}: ${why} (CONVENTIONS.md §6, The release rung)`);
880
973
  } else {
881
974
  add('release-policy', true, `${p.derived.axis} (${p.derived.row}${p.effective.route ? `, route ${p.effective.route}` : ''}): candidates auto, final ${p.effective.final}, test period ${p.effective.testPeriodDays}d`);
882
975
  }
@@ -904,23 +997,38 @@ function decide(facts) {
904
997
  if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
905
998
  else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
906
999
 
907
- const v = f.auto
1000
+ const computed = () => (f.auto
908
1001
  ? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
909
- : decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
1002
+ : decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags }));
1003
+ let v;
1004
+ if (library && versionSourceOf(p) === 'manifest') {
1005
+ // #590: the manifest is the version; the signals only decide whether it under-declares a break.
1006
+ if (f.override && f.override.bump) v = { ok: false, detail: `--bump ${f.override.bump} has nothing to override — on route library-fast with release.version-source: manifest the version is the manifest's; bump it on trunk` };
1007
+ else {
1008
+ const sig = f.auto ? (f.auto.signals || {}) : null;
1009
+ if (sig && sig.unread && sig.unread.length) v = { ok: false, unread: true, detail: `a bump signal could not be read — fail closed: ${sig.unread.join('; ')}` };
1010
+ else {
1011
+ const breaking = sig ? (sig.breaking || [])
1012
+ : (f.suggestion && f.suggestion.bump === 'major' ? [f.suggestion.why || 'a breaking change'] : []);
1013
+ v = decideManifestVersion({ lastFinal: f.lastFinal, manifests: f.manifests, tags: f.tags, breaking, migration: f.auto ? f.auto.migration : f.migration });
1014
+ if (v.fallback) v = computed();
1015
+ }
1016
+ }
1017
+ } else v = computed();
910
1018
  add('version', v.ok, v.detail, isUnread(v));
911
1019
  // "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
912
1020
  if (f.auto && v.nothing) noop = true;
913
1021
 
914
1022
  let tag = null;
915
1023
  let derivable = [];
916
- if (v.ok && fast) {
1024
+ if (v.ok && finalRoute) {
917
1025
  const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
918
1026
  if (finalHere.length) {
919
1027
  add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
920
1028
  if (f.auto) noop = true;
921
1029
  } else {
922
1030
  tag = v.version;
923
- add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
1031
+ add('already-final', true, `next final: ${tag} (no candidate — route ${fast ? 'deploy-tag-fast' : 'library-fast'})`);
924
1032
  }
925
1033
  } else if (v.ok) {
926
1034
  const here = candidateNumbers(f.tagsAtSha || [], v.version);
@@ -966,6 +1074,10 @@ function decide(facts) {
966
1074
  const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
967
1075
  add('migration-grant', mig.ok, mig.detail, !f.migrations || isUnread(mig));
968
1076
  if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
1077
+ } else if (library) {
1078
+ // #590: a human veto still holds an automatic final; nothing else the fast route adds applies.
1079
+ const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
1080
+ add('release-hold', h.ok, h.detail, !f.holds || isUnread(h));
969
1081
  }
970
1082
 
971
1083
  const refusals = checks.filter((c) => !c.ok);
@@ -981,7 +1093,7 @@ function decide(facts) {
981
1093
  signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
982
1094
  derivable,
983
1095
  versionSourceDeclared: !!(p && p.effective && p.effective.versionSourceDeclared),
984
- final: fast, grant, handoff,
1096
+ final: finalRoute, route: finalRoute ? (fast ? 'deploy-tag-fast' : 'library-fast') : null, grant, handoff,
985
1097
  healthGate: fast ? p.effective.healthGate : null,
986
1098
  };
987
1099
  }
@@ -996,8 +1108,9 @@ function tagMessage(verdict, { sha, lastFinal }) {
996
1108
  // #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
997
1109
  // reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
998
1110
  const fast = !!verdict.final;
1111
+ const route = verdict.route || 'deploy-tag-fast';
999
1112
  const lines = [
1000
- fast ? `${verdict.tag} — release (colab release cut, deploy-tag-fast)` : `${verdict.tag} — release candidate (colab release cut)`,
1113
+ fast ? `${verdict.tag} — release (colab release cut, ${route})` : `${verdict.tag} — release candidate (colab release cut)`,
1001
1114
  '',
1002
1115
  `Commit: ${sha}`,
1003
1116
  `Since: ${lastFinal}`,
@@ -1015,14 +1128,18 @@ function tagMessage(verdict, { sha, lastFinal }) {
1015
1128
  'Conditions (CONVENTIONS.md §6):',
1016
1129
  ...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
1017
1130
  '',
1018
- 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.',
1131
+ fast
1132
+ ? (route === 'library-fast'
1133
+ ? 'A final with no candidate: route library-fast — a library released per merge; nothing deploys from this tag (CONVENTIONS.md §6).'
1134
+ : 'A final with no candidate: route deploy-tag-fast, by the operator\'s grant (CONVENTIONS.md §6).')
1135
+ : 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
1019
1136
  ];
1020
1137
  return lines.join('\n') + '\n';
1021
1138
  }
1022
1139
 
1023
1140
  module.exports = {
1024
1141
  CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
1025
- isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
1142
+ isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1026
1143
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
1027
1144
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
1028
1145
  fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,