@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

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.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -46,12 +46,27 @@
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');
54
68
  const releaseTag = require('./release-tag');
69
+ const { stripCode } = require('./instruction-file');
55
70
 
56
71
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
57
72
  const BUMPS = Object.freeze(['patch', 'minor']);
@@ -64,11 +79,37 @@ const BUMPS = Object.freeze(['patch', 'minor']);
64
79
  const RELEASE_BRANCH = 'main';
65
80
 
66
81
  const CONDITIONS = Object.freeze([
67
- 'release-policy', 'cadence', 'promotion', 'prerelease-trigger', 'version', 'already-candidate',
82
+ 'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
68
83
  ...releaseTag.PRE_TAG_CONDITIONS,
69
84
  'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
85
+ 'final-grant', 'release-hold', 'migration-grant',
86
+ ]);
87
+
88
+ /**
89
+ * #467: the refusals that do NOT clear by themselves. A run refused on one of these refuses again on
90
+ * the next run and the one after — nothing but a human act (a first final tag, a fixed marker, a
91
+ * fixed manifest, a recorded grant) moves it — so the release workflow reports it as a STALL, an
92
+ * error annotation, never as the routine warning a CI-still-running refusal gets. The rest are
93
+ * transient: `ci-green` / `full-suite` (a run in flight, a red run the next merge fixes), an UNREAD
94
+ * anything (a read that failed — the next run reads again), and `release-hold` (a deliberate human
95
+ * veto is not a stall; it is the system working). Classified in decide() as `standing`.
96
+ */
97
+ const STANDING_CONDITIONS = Object.freeze([
98
+ 'release-policy', 'prerelease-trigger', 'version', 'schema-additive', 'switch-dependencies',
99
+ ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant',
70
100
  ]);
71
101
 
102
+ /** #446: the conditions only route deploy-tag-fast reports. */
103
+ const FAST_CONDITIONS = Object.freeze(['spacing', 'already-final', 'final-grant', 'release-hold', 'migration-grant']);
104
+
105
+ /** #446: the label a human puts on an issue to veto a release — the same one release-finalize reads. */
106
+ const HOLD_LABEL = 'release-hold';
107
+
108
+ /** #446: is this policy the fast route, where `cut --auto` tags the final itself? */
109
+ function isFastRoute(policy) {
110
+ return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
111
+ }
112
+
72
113
  /** The file a major's migration section is read from, at the candidate commit (#422). */
73
114
  const MIGRATION_FILE = 'MIGRATION.md';
74
115
 
@@ -344,7 +385,7 @@ function parseMigrationSection(text, version) {
344
385
  function decideAutoVersion({ lastFinal, signals, migration, tags }) {
345
386
  const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
346
387
  const s = signals || { total: 0, breaking: [], minor: [], patch: [], unread: [] };
347
- if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`);
388
+ if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`, { unread: true });
348
389
  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');
349
390
  const last = parseVersion(lastFinal);
350
391
  if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compute a bump from it`);
@@ -390,6 +431,45 @@ function cadenceVerdict({ candidates, perDay, now }) {
390
431
  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
432
  }
392
433
 
434
+ // ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
435
+
436
+ /**
437
+ * Finals at least `spacingHours` apart. `finals` is [{ name, date }] for every final tag (tagger
438
+ * date) — a human's final counts as much as an automatic one. Returns { ok, detail, nextAt }; not ok
439
+ * is a NO-OP for the caller, never a refusal, so the first run after the window tags main's head.
440
+ */
441
+ function spacingVerdict({ finals, spacingHours, now }) {
442
+ if (!spacingHours) return { ok: true, detail: 'no final spacing on this route', nextAt: null };
443
+ const nowMs = Date.parse(now);
444
+ const dated = (finals || []).map((f) => ({ ...f, ms: Date.parse(f.date) }))
445
+ .filter((f) => !Number.isNaN(f.ms) && f.ms <= nowMs).sort((a, b) => a.ms - b.ms);
446
+ if (!dated.length) return { ok: true, detail: 'no earlier final to space from', nextAt: null };
447
+ const last = dated[dated.length - 1];
448
+ const nextMs = last.ms + spacingHours * 3600000;
449
+ if (nowMs >= nextMs) return { ok: true, detail: `last final ${last.name} at ${new Date(last.ms).toISOString()}, spacing ${spacingHours}h`, nextAt: null };
450
+ const nextAt = new Date(nextMs).toISOString();
451
+ 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 };
452
+ }
453
+
454
+ /**
455
+ * The human veto, repo-wide: `issues` is the open-issue list (null = unread — never "no hold").
456
+ * Any open issue carrying `release-hold` holds the next final; the fast route has no candidate issue
457
+ * to put the label on, so a human may put it on any issue, and only a human removes it.
458
+ */
459
+ function holdsVerdict(issues) {
460
+ if (issues === null || issues === undefined) return { ok: false, unread: true, detail: `the open issues could not be read — an unread ${HOLD_LABEL} is not an absent one` };
461
+ const held = issues.filter((i) => i && (!i.state || String(i.state).toUpperCase() === 'OPEN')
462
+ && (i.labels || []).some((l) => (l && typeof l === 'object' ? l.name : l) === HOLD_LABEL)).map((i) => i.number);
463
+ return held.length
464
+ ? { 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` }
465
+ : { ok: true, detail: `no open issue carries ${HOLD_LABEL}` };
466
+ }
467
+
468
+ /** The command a human runs to let a migration ride an automatic final on the fast route. */
469
+ function migrationHandoff(tracking, version) {
470
+ return `COLAB_HUMAN=1 colab migration-grant ${tracking || '<tracking issue>'} --branch ${version}`;
471
+ }
472
+
393
473
  // ---- #443: the newest candidate names trunk's head -------------------------------------------
394
474
 
395
475
  /** Events that run DOWNSTREAM of the suite (the release workflow itself) — never part of "head is green". */
@@ -414,16 +494,22 @@ const DOWNSTREAM_EVENTS = Object.freeze(['workflow_run', 'schedule', 'workflow_d
414
494
  * whole suite-duration after it went green is one the release run did not tag.
415
495
  *
416
496
  * Returns { state, flag, detail, greenAt, cycleMs } — state is one of: off · named · nothing-owed ·
417
- * not-promotion · unread · not-green · pending · untagged. Only `untagged` flags.
497
+ * no-final · not-promotion · unread · not-green · pending · untagged. `untagged` and `no-final` flag.
498
+ *
499
+ * `no-final` (#467): candidates are automatic but there is no final tag to compute a bump from, so
500
+ * `release cut --auto` refuses on every run, forever, until a human tags the first version. That is a
501
+ * stall, not "nothing owed" — reading it as nothing-owed is how a repo sat green for days with no tag.
418
502
  */
419
503
  function headCandidateVerdict({ candidatesAuto, sha, tagsAtSha, owed, runs, promotion, now }) {
420
504
  const at = `main@${String(sha || '').slice(0, 7)}`;
421
- const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged', detail, greenAt: null, cycleMs: null, ...extra });
505
+ const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged' || state === 'no-final', detail, greenAt: null, cycleMs: null, ...extra });
422
506
  if (!candidatesAuto) return out('off', 'candidates are not automatic here — nothing names the head by itself');
423
507
  const named = (tagsAtSha || []).filter((t) => /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t));
424
508
  if (named.length) return out('named', `${at} is ${named.join(', ')}`);
425
509
  if (owed === 0) return out('nothing-owed', `nothing merged on main since the last final — no candidate is owed`);
426
- if (owed === null || owed === undefined) return out('nothing-owed', 'no final tag yet — the first version is a human decision, so no candidate is owed');
510
+ if (owed === null || owed === undefined) {
511
+ return out('no-final', 'no final tag yet — `release cut --auto` refuses every run until a human tags the first version (CONVENTIONS.md §6, Versioning); release stalled');
512
+ }
427
513
  if (promotion && !promotion.ok) return out('not-promotion', `${at} is not a promotion of trunk — --auto never cuts it (${promotion.detail})`);
428
514
  if (!Array.isArray(runs)) return out('unread', `gh run list failed — cannot tell whether ${at} is green`);
429
515
  const suite = runs.filter((r) => r && !DOWNSTREAM_EVENTS.includes(r.event));
@@ -452,6 +538,28 @@ function prereleaseArgs(tag, notesFile) {
452
538
  return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--prerelease', '--latest=false'];
453
539
  }
454
540
 
541
+ /** #446: a deploy-tag-fast final's GitHub Release — a full release, marked latest. */
542
+ function finalReleaseArgs(tag, notesFile) {
543
+ return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--latest'];
544
+ }
545
+
546
+ /**
547
+ * #446: the tracking issue a fast-route migration hand-off opens. Same marker as release-finalize's
548
+ * (`<!-- colab:release version=… -->`), so every reader finds it; the text says what is owed here —
549
+ * a migration grant, not a candidate's test period.
550
+ */
551
+ function handoffTrackingBody(version) {
552
+ return [
553
+ `<!-- colab:release version=${version} -->`,
554
+ '',
555
+ `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.`,
556
+ '',
557
+ '- 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.',
558
+ `- **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}.`,
559
+ `- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
560
+ ].join('\n') + '\n';
561
+ }
562
+
455
563
  // ---- §6 condition 2: the full suite ------------------------------------------------------------
456
564
 
457
565
  /**
@@ -577,11 +685,16 @@ const MARKER_RE = /<!--\s*colab:switch\b([\s\S]*?)-->/g;
577
685
  * Returns { markers: [{ name, needs: [], role: null|'add'|'remove' }], malformed: [text] } — an
578
686
  * unknown token, a bad name, `needs` on a child, or two markers for one name disagreeing are all
579
687
  * `malformed`: "not cleared", reported, never defaulted.
688
+ *
689
+ * #466: fenced code blocks and inline code spans are blanked first (`stripCode`, the same reader
690
+ * the instruction-file import scan uses), so a body that QUOTES the marker family — prose such as
691
+ * "the `<!-- colab:switch -->` marker" — is documentation, not a malformed marker blocking every
692
+ * release. A real marker sits outside code, so it is still read, and still refused when malformed.
580
693
  */
581
694
  function parseSwitchMarkers(body) {
582
695
  const markers = [];
583
696
  const malformed = [];
584
- const text = String(body || '');
697
+ const text = stripCode(String(body || '')).join('\n');
585
698
  let m;
586
699
  MARKER_RE.lastIndex = 0;
587
700
  while ((m = MARKER_RE.exec(text)) !== null) {
@@ -632,7 +745,7 @@ function closedDone(issue) {
632
745
  * here: this is the release-time consequence, not the edge audit.
633
746
  */
634
747
  function switchVerdict(issues) {
635
- if (issues === null || issues === undefined) return { ok: false, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
748
+ if (issues === null || issues === undefined) return { ok: false, unread: true, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
636
749
  const problems = [];
637
750
  const needsOf = new Map(); // name -> { needs: [..], from: #N }
638
751
  const declared = new Set();
@@ -706,12 +819,24 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
706
819
  function decide(facts) {
707
820
  const f = facts || {};
708
821
  const checks = [];
709
- const add = (condition, ok, detail) => checks.push({ condition, ok: !!ok, detail });
822
+ // #467: `unread` marks a failure that is a failed READ, not a measured fact — the next run reads
823
+ // again, so it is never a standing refusal. Kept out of the check rows (their shape is frozen).
824
+ const unreadSet = new Set();
825
+ const add = (condition, ok, detail, unread) => {
826
+ checks.push({ condition, ok: !!ok, detail });
827
+ if (!ok && unread) unreadSet.add(condition);
828
+ };
829
+ const isUnread = (verdict) => !!(verdict && verdict.unread);
710
830
 
711
831
  const p = f.policy;
712
- if (!p) add('release-policy', false, 'no release policy was evaluated');
832
+ const fast = isFastRoute(p) && !(p.findings && p.findings.length);
833
+ if (!p) add('release-policy', false, 'no release policy was evaluated', true);
713
834
  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') {
835
+ else if (fast && !f.auto) {
836
+ 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');
837
+ } else if (fast) {
838
+ 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`);
839
+ } else if (p.effective.candidates !== 'auto') {
715
840
  const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
716
841
  add('release-policy', false, narrowed
717
842
  ? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
@@ -724,12 +849,17 @@ function decide(facts) {
724
849
  let noop = false;
725
850
  if (f.auto) {
726
851
  const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
727
- add('cadence', cad.ok, cad.detail);
852
+ add('cadence', cad.ok, cad.detail, !f.auto.cadence);
728
853
  if (!cad.ok) noop = !!f.auto.cadence;
854
+ if (fast) {
855
+ const sp = f.auto.spacing || { ok: false, detail: 'final spacing not measured' };
856
+ add('spacing', sp.ok, sp.detail);
857
+ if (!sp.ok && f.auto.spacing) noop = true;
858
+ }
729
859
  // #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
730
860
  const pr = f.auto.promotion;
731
861
  if (pr) {
732
- add('promotion', pr.ok, pr.detail);
862
+ add('promotion', pr.ok, pr.detail, isUnread(pr));
733
863
  if (!pr.ok && !pr.unread) noop = true;
734
864
  }
735
865
  }
@@ -741,13 +871,22 @@ function decide(facts) {
741
871
  const v = f.auto
742
872
  ? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
743
873
  : decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
744
- add('version', v.ok, v.detail);
874
+ add('version', v.ok, v.detail, isUnread(v));
745
875
  // "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
746
876
  if (f.auto && v.nothing) noop = true;
747
877
 
748
878
  let tag = null;
749
879
  let derivable = [];
750
- if (v.ok) {
880
+ if (v.ok && fast) {
881
+ const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
882
+ if (finalHere.length) {
883
+ add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
884
+ if (f.auto) noop = true;
885
+ } else {
886
+ tag = v.version;
887
+ add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
888
+ }
889
+ } else if (v.ok) {
751
890
  const here = candidateNumbers(f.tagsAtSha || [], v.version);
752
891
  if (here.length) {
753
892
  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`);
@@ -763,7 +902,10 @@ function decide(facts) {
763
902
  // #424: the three pre-tag checks, on the tag this run would create.
764
903
  if (tag) {
765
904
  for (const c of releaseTag.preTagChecks({ tag, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: RELEASE_BRANCH, versionSource: versionSourceOf(p) })) {
766
- add(c.condition, c.ok, c.detail);
905
+ // An unread manifest list or an unmeasured ancestry is a failed read, not a wrong manifest.
906
+ const unreadPre = (c.condition === 'manifest-version' && (f.manifests === null || f.manifests === undefined))
907
+ || (c.condition === 'on-trunk' && !f.ancestry);
908
+ add(c.condition, c.ok, c.detail, unreadPre);
767
909
  if (c.derivable && c.derivable.length) derivable = c.derivable;
768
910
  }
769
911
  } else if (f.ancestry && f.ancestry.shallow) {
@@ -772,17 +914,39 @@ function decide(facts) {
772
914
  }
773
915
 
774
916
  for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
775
- if (!verdict) add(condition, false, 'not measured');
776
- else add(condition, verdict.ok, verdict.detail);
917
+ if (!verdict) add(condition, false, 'not measured', true);
918
+ else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
919
+ }
920
+
921
+ // #446: what the fast route keeps in place of the test period it does not have.
922
+ let handoff = null;
923
+ let grant = null;
924
+ if (fast) {
925
+ const g = f.finalGrant || { ok: false, detail: `release.final-grant #${p.effective.finalGrant.issue} was not resolved — an unresolved grant is not a grant` };
926
+ add('final-grant', g.ok, g.detail, !f.finalGrant || isUnread(g));
927
+ if (g.ok) grant = { issue: p.effective.finalGrant.issue, ruledBy: g.ruledBy || null };
928
+ const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
929
+ add('release-hold', h.ok, h.detail, !f.holds || isUnread(h));
930
+ const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
931
+ add('migration-grant', mig.ok, mig.detail, !f.migrations || isUnread(mig));
932
+ if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
777
933
  }
778
934
 
779
935
  const refusals = checks.filter((c) => !c.ok);
780
936
  const ok = refusals.length === 0 && !!tag;
937
+ // #467: the refusals that will not clear by themselves — empty on ok and on a no-op, whose
938
+ // "failures" (cadence, nothing merged, head already a candidate) are the route holding.
939
+ const standing = ok || noop ? [] : refusals
940
+ .filter((c) => STANDING_CONDITIONS.includes(c.condition) && !unreadSet.has(c.condition))
941
+ .map((c) => c.condition);
781
942
  return {
782
- ok, noop: !ok && noop, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
943
+ ok, noop: !ok && noop, standing, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
783
944
  bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
784
945
  signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
785
946
  derivable,
947
+ versionSourceDeclared: !!(p && p.effective && p.effective.versionSourceDeclared),
948
+ final: fast, grant, handoff,
949
+ healthGate: fast ? p.effective.healthGate : null,
786
950
  };
787
951
  }
788
952
 
@@ -793,8 +957,11 @@ function versionSourceOf(policy) {
793
957
 
794
958
  /** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
795
959
  function tagMessage(verdict, { sha, lastFinal }) {
960
+ // #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
961
+ // reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
962
+ const fast = !!verdict.final;
796
963
  const lines = [
797
- `${verdict.tag} — release candidate (colab release cut)`,
964
+ fast ? `${verdict.tag} — release (colab release cut, deploy-tag-fast)` : `${verdict.tag} — release candidate (colab release cut)`,
798
965
  '',
799
966
  `Commit: ${sha}`,
800
967
  `Since: ${lastFinal}`,
@@ -802,21 +969,28 @@ function tagMessage(verdict, { sha, lastFinal }) {
802
969
  '',
803
970
  ...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
804
971
  ...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
805
- ...(verdict.derivable && verdict.derivable.length ? [`Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
972
+ ...(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)`] : []),
973
+ ...(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`, ''] : []),
974
+ // #484: a defaulted `tag` says so — the stale manifest is named on every cut, so an artifact that
975
+ // reads it unstamped is visible here rather than discovered by a user.
976
+ ...(verdict.derivable && verdict.derivable.length ? [verdict.versionSourceDeclared
977
+ ? `Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`
978
+ : `Derivable manifests (release.version-source: tag — the default on a route that tags automatically, #484; not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
806
979
  'Conditions (CONVENTIONS.md §6):',
807
980
  ...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
808
981
  '',
809
- 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
982
+ 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
983
  ];
811
984
  return lines.join('\n') + '\n';
812
985
  }
813
986
 
814
987
  module.exports = {
815
- CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH,
988
+ CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
989
+ isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
816
990
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
817
991
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
818
992
  fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
819
993
  parseSwitchMarkers, switchVerdict,
820
994
  promotionVerdict, decide, tagMessage, versionSourceOf,
821
- DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs,
995
+ DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,
822
996
  };
@@ -9,8 +9,8 @@
9
9
  * PURE BY CONSTRUCTION, the release-cut.js posture: no git, no network, no `gh`, no clock (`now` is
10
10
  * passed in). The CLI in tools/colab is the measuring half.
11
11
  *
12
- * WHERE PER-CANDIDATE STATE LIVES (the contract futurelastic/hangar#125 reads — change it and every
13
- * consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
12
+ * WHERE PER-CANDIDATE STATE LIVES (the contract a downstream dashboard's release view reads — change
13
+ * it and every consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
14
14
  *
15
15
  * - the candidates are the annotated `vX.Y.Z-rc.N` tags on origin that `colab release cut` made
16
16
  * (first line of the tag message ends `(colab release cut)`); nothing else stores them;
@@ -56,7 +56,11 @@
56
56
 
57
57
  const releaseTag = require('./release-tag');
58
58
 
59
- const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
59
+ // The tracking marker and the event marker are wire format: codec/release.js (#498, epic #496),
60
+ // re-exported below under the names this module always had. VERSION_RE is the codec's, so a
61
+ // marker's version and a tag's version are judged by one pattern.
62
+ const releaseCodec = require('./codec/release');
63
+ const { VERSION_RE } = releaseCodec;
60
64
  const CANDIDATE_RE = /^(v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))-rc\.([1-9][0-9]*)$/;
61
65
  const CUT_SUBJECT_SUFFIX = '(colab release cut)';
62
66
  const HOLD_LABEL = 'release-hold';
@@ -93,20 +97,11 @@ function parseCandidate(tag) {
93
97
 
94
98
  // ---- the tracking issue -------------------------------------------------------------------------
95
99
 
96
- const RELEASE_MARKER_RE = /<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
97
-
98
100
  /** The version a tracking issue's body declares, or null. Only the marker counts, never the title. */
99
- function parseReleaseMarker(body) {
100
- const m = RELEASE_MARKER_RE.exec(String(body || ''));
101
- return m && parseVersion(m[1]) ? m[1] : null;
102
- }
103
-
104
- function releaseMarker(version) { return `<!-- colab:release version=${version} -->`; }
105
-
101
+ const parseReleaseMarker = releaseCodec.decodeTrackingMarker;
102
+ const releaseMarker = releaseCodec.encodeTrackingMarker;
106
103
  /** `<!-- colab:release-event k=v … -->`, keys in the order given. */
107
- function eventMarker(fields) {
108
- return `<!-- colab:release-event ${Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(' ')} -->`;
109
- }
104
+ const eventMarker = releaseCodec.encodeReleaseEvent;
110
105
 
111
106
  /** True when some comment body already carries exactly this event marker — a re-run posts nothing twice. */
112
107
  function hasEvent(comments, fields) {
@@ -202,18 +197,102 @@ function openCandidates(tags, remote = 'origin') {
202
197
  }
203
198
 
204
199
  /**
205
- * --auto (#423): `evaluations` is [{ candidate, verdict }] NEWEST FIRST, one decide() per candidate
206
- * judged. Returns { candidate, verdict, skipped: [{ tag, state }] }:
200
+ * #468: the one check that explains a verdict's state, as `<condition>: <detail>` — or null when the
201
+ * state needs no explaining (finalized, already-final). What a reader of a run needs is WHY this
202
+ * candidate did not finalize, not the whole checklist again.
203
+ */
204
+ function stateDetail(verdict) {
205
+ const v = verdict || {};
206
+ const checks = v.checks || [];
207
+ const failing = (name) => checks.find((c) => c.condition === name && !c.ok);
208
+ const fmt = (c) => (c ? `${c.condition}: ${c.detail}` : null);
209
+ switch (v.state) {
210
+ case 'finalized': case 'already-final': return null;
211
+ case 'held': return fmt(failing('release-hold'));
212
+ case 'needs-new-candidate': return fmt(failing('regressions') || failing('trunk-green'));
213
+ case 'testing': return fmt(failing('test-period') || failing('trunk-green'));
214
+ case 'candidate-ready': return fmt(failing('human'));
215
+ default: return fmt(checks.find((c) => c.required !== false && !c.ok) || checks.find((c) => !c.ok));
216
+ }
217
+ }
218
+
219
+ /**
220
+ * --auto (#423): `evaluations` is [{ candidate, verdict, period? }] NEWEST FIRST, one decide() per
221
+ * candidate judged. Returns { candidate, verdict, skipped: [{ tag, state, detail, endsAt }] }:
207
222
  * - any `held` verdict wins outright — a human veto is never walked around;
208
223
  * - else the first `finalized` (the newest candidate clean on its own clock);
209
224
  * - else the newest candidate's verdict (testing, refused …), with the older ones listed as skipped.
225
+ * #468: each skipped entry says why (stateDetail) and when its own period ends, so a run that
226
+ * finalizes nothing can say which candidate finals first — the fallback to the newest candidate
227
+ * otherwise reads exactly like "only the newest candidate is considered".
210
228
  */
211
229
  function pickNewestClean(evaluations) {
212
230
  const ev = evaluations || [];
213
231
  if (!ev.length) return { candidate: null, verdict: null, skipped: [] };
214
232
  const held = ev.find((e) => e.verdict.state === 'held');
215
233
  const pick = held || ev.find((e) => e.verdict.state === 'finalized') || ev[0];
216
- return { candidate: pick.candidate, verdict: pick.verdict, skipped: ev.filter((e) => e !== pick).map((e) => ({ tag: e.candidate.tag, state: e.verdict.state })) };
234
+ return {
235
+ candidate: pick.candidate,
236
+ verdict: pick.verdict,
237
+ skipped: ev.filter((e) => e !== pick).map((e) => ({
238
+ tag: e.candidate.tag, state: e.verdict.state, detail: stateDetail(e.verdict), endsAt: e.period ? e.period.endsAt : null,
239
+ })),
240
+ };
241
+ }
242
+
243
+ /**
244
+ * #468: is any red trunk run (`redAts`, ISO createdAt times from trunkGreenVerdict's `redAt`) inside
245
+ * this candidate's own window [start, endsAt)? The window is half-open exactly as trunkGreenVerdict
246
+ * reads it. True means the candidate would read `needs-new-candidate` — IF the red run's workflow is
247
+ * among the ones that vetted it; that is only known after a full judge, so a true here may be wrong
248
+ * in the safe direction only: a final delayed, never one made.
249
+ */
250
+ function windowHasRed(period, redAts) {
251
+ if (!period) return null;
252
+ const startMs = Date.parse(period.start);
253
+ const endMs = Date.parse(period.endsAt);
254
+ return (redAts || []).find((t) => { const ms = Date.parse(t); return ms >= startMs && ms < endMs; }) || null;
255
+ }
256
+
257
+ /**
258
+ * #468: why a run produced no final, in one line, plus the candidate that finals first.
259
+ * state, candidate, checks the picked verdict (and its candidate) — the run's reported state
260
+ * period the picked candidate's own period, or null
261
+ * skipped pickNewestClean's skipped list, the cheap-skipped testing ones included
262
+ * now ISO timestamp (the module stays clock-free)
263
+ * Returns null when a final was made (or the version is already final); else { line, next } where
264
+ * `next` = { tag, endsAt, hoursLeft } for the TESTING candidate whose own period ends soonest, or null.
265
+ */
266
+ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
267
+ if (state === 'finalized' || state === 'already-final') return null;
268
+ const nowMs = Date.parse(now);
269
+ const testing = [
270
+ ...(state === 'testing' && candidate && period ? [{ tag: candidate.tag, endsAt: period.endsAt }] : []),
271
+ ...(skipped || []).filter((x) => x.state === 'testing' && x.endsAt),
272
+ ].filter((x) => !Number.isNaN(Date.parse(x.endsAt)));
273
+ testing.sort((a, b) => Date.parse(a.endsAt) - Date.parse(b.endsAt) || String(a.tag).localeCompare(String(b.tag)));
274
+ const first = testing[0] || null;
275
+ const next = first
276
+ ? { tag: first.tag, endsAt: first.endsAt, hoursLeft: Number.isNaN(nowMs) ? null : Math.max(0, Math.ceil((Date.parse(first.endsAt) - nowMs) / 3600000)) }
277
+ : null;
278
+ const nextText = next ? `${next.tag} is first, its own test period ends ${next.endsAt}${next.hoursLeft !== null ? ` (${next.hoursLeft}h left)` : ''}` : null;
279
+ const why = stateDetail({ state, checks });
280
+ const tag = candidate ? candidate.tag : 'no candidate';
281
+ let line;
282
+ if (state === 'no-candidate') line = `no open candidate to finalize${why ? ` — ${why}` : ''}`;
283
+ else if (state === 'testing') {
284
+ const allTesting = (skipped || []).every((x) => x.state === 'testing');
285
+ line = allTesting && nextText
286
+ ? `no candidate's own test period has elapsed clean — ${nextText}`
287
+ : `${tag} is still testing (${why || 'test period'})${nextText ? `; ${nextText}` : ''}`;
288
+ } else line = `${tag}: ${state}${why ? ` — ${why}` : ''}${nextText ? `; ${nextText}` : ''}`;
289
+ const older = (skipped || []).filter((x) => x.state !== 'testing');
290
+ if (older.length && state === 'testing') {
291
+ const counts = {};
292
+ for (const x of older) counts[x.state] = (counts[x.state] || 0) + 1;
293
+ line += `; older candidates: ${Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ')}`;
294
+ }
295
+ return { line, next };
217
296
  }
218
297
 
219
298
  // ---- the test period ----------------------------------------------------------------------------
@@ -263,7 +342,9 @@ function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows
263
342
  const inWindow = runs.filter((r) => r && Date.parse(r.createdAt) >= startMs && Date.parse(r.createdAt) < endMs && suite.has(r.workflowName || '(unnamed workflow)') && r.event !== 'pull_request');
264
343
  const red = inWindow.filter((r) => r.status === 'completed' && !NOT_RED.has(r.conclusion) && r.conclusion !== 'cancelled');
265
344
  if (red.length) {
266
- return { ok: false, permanent: true, pending: false, detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
345
+ // #468: redAt — when each red run started — lets an --auto walk skip older candidates whose
346
+ // window holds the same red run without paying a full judge for each (windowHasRed).
347
+ return { ok: false, permanent: true, pending: false, redAt: red.map((r) => r.createdAt), detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
267
348
  }
268
349
  const unsettled = [];
269
350
  let pending = inWindow.some((r) => r.status !== 'completed');
@@ -342,7 +423,7 @@ function regressionVerdict(edges, { periodStart }) {
342
423
  * evaluate. Returns { ok, detail }.
343
424
  */
344
425
  function migrationGrantVerdict({ paths, grant, since }) {
345
- if (paths === null || paths === undefined) return { ok: false, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
426
+ if (paths === null || paths === undefined) return { ok: false, unread: true, detail: 'the migration files since the last final could not be read — an unread migration is not an absent one' };
346
427
  if (!paths.length) return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
347
428
  const list = paths.join(', ');
348
429
  if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
@@ -397,6 +478,13 @@ function decide(facts) {
397
478
  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
479
  else add('release-policy', true, `${p.derived.axis} (${row}): final ${finalMode}, test period ${p.effective.testPeriodDays}d`);
399
480
  if (!checks[0].ok) return out('refused');
481
+ // #446: route deploy-tag-fast tags its finals in `release cut --auto`, with no candidate. A leftover
482
+ // candidate from an earlier route is superseded by the next final — never finalized here, where the
483
+ // grant would otherwise finalize an old -rc days after the operator chose the fast route.
484
+ if (p.effective.finalize === 'on-green-head') {
485
+ 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');
486
+ return out('no-candidate');
487
+ }
400
488
 
401
489
  const s = f.selection || { kind: 'none', detail: 'no candidate selected' };
402
490
  if (s.kind === 'none') { add('candidate', false, s.detail); return out('no-candidate'); }
@@ -490,9 +578,9 @@ function previousFinal(tagNames, version) {
490
578
  /** The event fields of a "released in" comment — one per issue per version. */
491
579
  function releasedEvent(version) { return { released: version }; }
492
580
 
493
- /** The comment body posted on each carried issue (marker included). */
581
+ /** The comment body posted on each carried issue (marker included) — codec `encodeReleasedComment`. */
494
582
  function releasedComment(version, sha) {
495
- return `${eventMarker(releasedEvent(version))}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
583
+ return releaseCodec.encodeReleasedComment({ version, sha });
496
584
  }
497
585
 
498
586
  /** The final tag's annotated message: which candidate, which period, every condition, who. */
@@ -515,7 +603,7 @@ module.exports = {
515
603
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
516
604
  parseVersion, compareVersions, parseCandidate,
517
605
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
518
- selectCandidate, openCandidates, pickNewestClean, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
606
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
519
607
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
520
608
  carriedIssues, previousFinal, releasedEvent, releasedComment,
521
609
  };