@futurelastic/colab-handbook 1.15.0-rc.3 → 1.15.0-rc.5

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.15.0-rc.3"
36
+ "version": "1.15.0-rc.5"
37
37
  }
package/tools/colab CHANGED
@@ -1652,7 +1652,7 @@ function commentOnce(repoAbs, num, fields, text) {
1652
1652
  * in (previous final, sha], minus `exclude` (the release tracking issues). Idempotent by event marker.
1653
1653
  * Shared by `release finalize` and, on route deploy-tag-fast (#446), `release cut`.
1654
1654
  */
1655
- function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1655
+ function announceCarried(repoAbs, { tagNames, exclude, version, sha, early = null }) {
1656
1656
  const prev = releaseFinalize.previousFinal(tagNames, version);
1657
1657
  if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
1658
1658
  const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
@@ -1663,7 +1663,7 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1663
1663
  const view = git.ghIssueView(repoAbs, n, ['comments']);
1664
1664
  if (!view) { skipped.push(n); continue; }
1665
1665
  if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
1666
- const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
1666
+ const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha, early));
1667
1667
  if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
1668
1668
  }
1669
1669
  return { range: `${prev}..${version}`, issues: nums, posted, skipped };
@@ -1967,7 +1967,7 @@ workflow refuses a private repo itself.
1967
1967
  (publish true, or nothing declared); exit 1 when the npm keys are declared but cannot publish.
1968
1968
  `;
1969
1969
 
1970
- const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name>]] [--dry] [--json]
1970
+ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name> [--early]]] [--dry] [--json]
1971
1971
 
1972
1972
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1973
1973
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
@@ -1999,7 +1999,8 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1999
1999
 
2000
2000
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
2001
2001
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
2002
- ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant human
2002
+ ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant
2003
+ early-final human
2003
2004
 
2004
2005
  regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
2005
2006
  began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
@@ -2037,16 +2038,26 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
2037
2038
  every row; release-hold and regressions as always. Newer candidates stay open
2038
2039
  for the next version — only versions below the final are closed as superseded
2039
2040
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
2040
- No field, flag or project.yml value lowers it, and it never shortens a test period.
2041
- Where the final is a human act the period is informational anyway, and
2042
- release.test-period: 0d declares none at all (#549)
2041
+ No field, flag or project.yml value lowers it, and on its own it never shortens a
2042
+ test period. Where the final is a human act the period is informational anyway,
2043
+ and release.test-period: 0d declares none at all (#549)
2044
+ --early with COLAB_HUMAN=1, --tag and --answered-by, on a route whose final is automatic
2045
+ (#627): finalize the newest candidate before its test period elapses. The floor
2046
+ binds the machine, not a person who answers for the release: test-period is
2047
+ reported, not required; trunk-green stays required over the elapsed part of the
2048
+ window, and every other check applies. The tag message, the tracking issue and
2049
+ every "Released in" comment record who answered and how much of the period had
2050
+ elapsed. Refused without the bar, on an older candidate, and where the final is
2051
+ already a human act (deploy-tag, or automatic only by release.final-grant).
2052
+ --auto never takes it
2043
2053
  --dry measure and report; open, post, tag and close nothing
2044
2054
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
2045
2055
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
2046
2056
  skipped (--auto: [{tag, state, detail?}] — the other open candidates),
2047
2057
  channel (null, or {channel, ok, action, detail} — the stable move, #445),
2048
2058
  announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
2049
- grant (null, or {issue, ruledBy} — the operator grant that made this final automatic) }
2059
+ grant (null, or {issue, ruledBy} — the operator grant that made this final automatic),
2060
+ early (null, or {answeredBy, elapsedHours, periodHours, at} — an early human final, #627) }
2050
2061
 
2051
2062
  Needs origin and gh (the tracking issue, runs and edges live on GitHub). Never cuts a candidate, never
2052
2063
  a major, never removes a label or an edge. Exit 0 when finalized (or would be) or candidate-ready; 1
@@ -2079,17 +2090,21 @@ function releaseHeavyFact(repoAbs, doc, cand) {
2079
2090
  function cmdReleaseFinalize(argv) {
2080
2091
  const opts = parseArgs(argv, {
2081
2092
  values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
2082
- flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
2093
+ flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '--early': 'early', '-h': 'help', '--help': 'help' },
2083
2094
  });
2084
2095
  if (opts.help) return print(HELP_RELEASE_FINALIZE);
2085
2096
  if (opts._.length) throw new UserError(`release finalize takes no positional arguments (got: ${opts._.join(' ')})`);
2086
2097
  // #423: --auto is the release workflow's mode. The human bar names one reviewed candidate; --auto
2087
2098
  // picks among them — the two never combine, so an unattended run can never carry a human's assertion.
2088
- if (opts.auto && (opts.tag || opts.answeredBy)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by, or drop --auto');
2099
+ if (opts.auto && (opts.tag || opts.answeredBy || opts.early)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by/--early, or drop --auto');
2089
2100
  const humanBar = !opts.auto && process.env.COLAB_HUMAN === '1' && !!opts.answeredBy;
2090
2101
  if (humanBar && !opts.tag) {
2091
2102
  throw new UserError('the human bar needs --tag <vX.Y.Z-rc.N>: it names the exact candidate the human reviewed, so a newer one cut meanwhile is never finalized in its place');
2092
2103
  }
2104
+ // #627: an early final is a human's act alone — refused before anything is read without the whole bar.
2105
+ if (opts.early && !humanBar) {
2106
+ throw new UserError('--early finalizes before the test period elapses only as a human act: run it with COLAB_HUMAN=1, --tag <vX.Y.Z-rc.N> and --answered-by <your name>');
2107
+ }
2093
2108
  const repoAbs = resolveRepo(opts);
2094
2109
  if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — the tracking issue, runs and regression edges live on GitHub`);
2095
2110
  const doc = projectDoc(repoAbs);
@@ -2222,7 +2237,8 @@ function cmdReleaseFinalize(argv) {
2222
2237
  ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2223
2238
  heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
2224
2239
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2225
- human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2240
+ human: { bar: humanBar, answeredBy: opts.answeredBy || null, early: !!opts.early },
2241
+ now, // #627: how much of the period an early final cut short
2226
2242
  });
2227
2243
  return { candidate: cand, verdict, period, tracking, trunk };
2228
2244
  };
@@ -2281,10 +2297,10 @@ function cmdReleaseFinalize(argv) {
2281
2297
  // #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
2282
2298
  // carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
2283
2299
  let announced = null;
2284
- const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2300
+ const announceRelease = (version, sha, early = null) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha, early });
2285
2301
  if (!opts.dry) {
2286
2302
  if (verdict.state === 'finalized') {
2287
- 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)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2303
+ const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1${verdict.early ? ', --early' : ''})` : `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)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2288
2304
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2289
2305
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2290
2306
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2318,13 +2334,13 @@ function cmdReleaseFinalize(argv) {
2318
2334
  `**${cand.tag} is ready.** The final tag is a human act on this repo — the one command, run by a human:\n\n\`\`\`sh\n${verdict.handoff}\n\`\`\``);
2319
2335
  }
2320
2336
  if (tagged) {
2321
- comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).`);
2337
+ comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).${verdict.early ? `\n\nEarly final: ${releaseFinalize.earlyLine(verdict.early)}.` : ''}`);
2322
2338
  close(tracking.number);
2323
2339
  }
2324
2340
  }
2325
2341
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2326
2342
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2327
- if (tagged) announced = announceRelease(cand.version, cand.sha);
2343
+ if (tagged) announced = announceRelease(cand.version, cand.sha, verdict.early || null);
2328
2344
  // Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
2329
2345
  // without --auto closed every other open version at once, because only the newest candidate could
2330
2346
  // ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
@@ -2358,7 +2374,7 @@ function cmdReleaseFinalize(argv) {
2358
2374
  lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
2359
2375
  periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
2360
2376
  state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
2361
- skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, channel,
2377
+ skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, early: verdict.early || null, channel,
2362
2378
  }, null, 2));
2363
2379
  } else {
2364
2380
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
@@ -2370,6 +2386,7 @@ function cmdReleaseFinalize(argv) {
2370
2386
  }
2371
2387
  print('');
2372
2388
  print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
2389
+ if (verdict.early) print(`early final: ${releaseFinalize.earlyLine(verdict.early)}`);
2373
2390
  if (why) print(`why no final: ${why.line}`);
2374
2391
  if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
2375
2392
  if (channel && channel.ok) print(`✓ ${channel.detail}`);
@@ -11747,6 +11764,12 @@ function classifyCiRunRaw(repoAbs, run, at) {
11747
11764
  const detail = n === 1 ? `1 run at ${at}: success` : `${n} runs at ${at}: all success`;
11748
11765
  return { ok: true, class: null, detail };
11749
11766
  }
11767
+ if (run.cancelledOnly) {
11768
+ // #628: one workflow's only run at this sha was cancelled — it verified nothing, and the other
11769
+ // workflows' success does not stand in for it. Name it so a human knows what to re-run.
11770
+ const c = run.cancelledOnly;
11771
+ return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: workflow "${c.workflowName}" never finished here — its only run${c.databaseId ? ` (run ${c.databaseId})` : ''} was cancelled, so it verified nothing; re-run it (#628)` };
11772
+ }
11750
11773
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=completed conclusion=${run.conclusion || 'none'}` };
11751
11774
  }
11752
11775
  if (run.status === 'none') {
@@ -12,6 +12,9 @@ export function decodeTrackingMarker(body: string | null | undefined): string |
12
12
  export function encodeReleaseEvent(fields: Record<string, string | number>): string;
13
13
  export function decodeReleaseEvent(marker: string | null | undefined): Record<string, string> | null;
14
14
 
15
- export function encodeReleasedComment(c?: { version: string; sha: string }): string;
16
- /** `sha` is the 7-character form the comment carries. */
17
- export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string } | null;
15
+ /** #627: an early human final — who answered, and how much of the test period had elapsed. */
16
+ export interface EarlyFinal { answeredBy: string; elapsedHours: number; periodHours: number }
17
+
18
+ export function encodeReleasedComment(c?: { version: string; sha: string; early?: EarlyFinal | null }): string;
19
+ /** `sha` is the 7-character form the comment carries; `early` only when the comment names an early final. */
20
+ export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string; early?: EarlyFinal } | null;
@@ -11,7 +11,8 @@
11
11
  * event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
12
12
  * tracking issue, keys in the order written. Its exact presence is what makes
13
13
  * a re-run post nothing twice, so key order is part of the wire format.
14
- * released comment — the event marker `released=vX.Y.Z` plus one visible line, posted once on
14
+ * released comment — the event marker `released=vX.Y.Z` plus one visible line (two after an early
15
+ * human final, #627), posted once on
15
16
  * each issue a release carried.
16
17
  *
17
18
  * Deciding which candidate, which period, and whether to finalize stays in
@@ -21,7 +22,7 @@
21
22
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
22
23
  const TRACKING_MARKER_RE = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
23
24
  const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
24
- const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
25
+ const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.(?:\nEarly final: answered by ([^\n]+) after ([0-9]+)h of the ([0-9]+)h test period\.)?$/;
25
26
 
26
27
  /** `vX.Y.Z` → the tracking marker. */
27
28
  function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
@@ -52,16 +53,24 @@ function decodeReleaseEvent(marker) {
52
53
  return out;
53
54
  }
54
55
 
55
- /** `{version, sha}` → the "released in" comment; `sha` is shortened to 7 characters. */
56
- function encodeReleasedComment({ version, sha } = {}) {
57
- return `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
56
+ /**
57
+ * `{version, sha, early?}` → the "released in" comment; `sha` is shortened to 7 characters. `early`
58
+ * ({answeredBy, elapsedHours, periodHours}, #627) adds one line naming an early human final; without
59
+ * it the comment is byte-identical to the two-line form every earlier final wrote.
60
+ */
61
+ function encodeReleasedComment({ version, sha, early = null } = {}) {
62
+ const base = `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
63
+ if (!early || !Number.isInteger(early.elapsedHours) || !Number.isInteger(early.periodHours)) return base;
64
+ return `${base}\nEarly final: answered by ${String(early.answeredBy).replace(/\s+/g, ' ').trim()} after ${early.elapsedHours}h of the ${early.periodHours}h test period.`;
58
65
  }
59
66
 
60
- /** A "released in" comment → `{version, sha}` (sha as written, 7 characters), or null. */
67
+ /** A "released in" comment → `{version, sha}` (sha as written, 7 characters) plus `early` when it names one (#627), or null. */
61
68
  function decodeReleasedComment(body) {
62
69
  const m = RELEASED_COMMENT_RE.exec(String(body == null ? '' : body).replace(/\r\n/g, '\n').trim());
63
70
  if (!m || m[1] !== m[2]) return null;
64
- return { version: m[1], sha: m[3] };
71
+ const out = { version: m[1], sha: m[3] };
72
+ if (m[4] !== undefined) out.early = { answeredBy: m[4], elapsedHours: Number(m[5]), periodHours: Number(m[6]) };
73
+ return out;
65
74
  }
66
75
 
67
76
  module.exports = {
@@ -745,6 +745,19 @@
745
745
  "sha": "3e2f810"
746
746
  },
747
747
  "note": "synthetic: no final has announced on an issue yet"
748
+ },
749
+ {
750
+ "wire": "<!-- colab:release-event released=v2.4.0 -->\nReleased in **v2.4.0** (`9c1d2e3`).\nEarly final: answered by Ada Lovelace after 30h of the 72h test period.",
751
+ "decoded": {
752
+ "version": "v2.4.0",
753
+ "sha": "9c1d2e3",
754
+ "early": {
755
+ "answeredBy": "Ada Lovelace",
756
+ "elapsedHours": 30,
757
+ "periodHours": 72
758
+ }
759
+ },
760
+ "note": "synthetic: an early human final (#627) — no early final has announced yet"
748
761
  }
749
762
  ]
750
763
  },
package/tools/lib/git.js CHANGED
@@ -1304,6 +1304,22 @@ function summarizeRepoOwnedRuns(forSha, sha) {
1304
1304
  );
1305
1305
  if (notGreen) return { status: 'completed', conclusion: notGreen.conclusion, sha, createdAt: notGreen.createdAt || null, databaseId: notGreen.databaseId || null, runCount };
1306
1306
 
1307
+ // #628: a NAMED workflow whose head is `cancelled` has no run at this sha that ran to the end —
1308
+ // newestRunPerWorkflow never lets a cancelled row stand for a workflow that has a non-neutral
1309
+ // run (#92), so a cancelled head means cancelled is all it has. That workflow verified nothing,
1310
+ // and a sibling workflow's success must not carry the verdict for it. Measured: the only test
1311
+ // workflow at a trunk head hung and was cancelled, and the head read GREEN on a lint workflow's
1312
+ // success. Unnamed rows (older reads, hand-built fixtures) stay neutral exactly as before — they
1313
+ // cannot be told apart from a superseded straggler of a passing run, which is #92's case.
1314
+ const cancelledOnly = forSha.find((x) => x && x.workflowName && x.status === 'completed' && x.conclusion === 'cancelled');
1315
+ if (cancelledOnly) {
1316
+ return {
1317
+ status: 'completed', conclusion: 'cancelled', sha, createdAt: cancelledOnly.createdAt || null,
1318
+ databaseId: cancelledOnly.databaseId || null, runCount,
1319
+ cancelledOnly: { workflowName: cancelledOnly.workflowName, databaseId: cancelledOnly.databaseId || null },
1320
+ };
1321
+ }
1322
+
1307
1323
  // A green verdict is owed only when EVERY sibling at this sha has finished (#307). A row that is
1308
1324
  // still queued/in_progress has not passed — it has not run — so picking the first completed
1309
1325
  // success here would stamp `runCount` (the FULL sibling count) onto a verdict that inspected one
@@ -78,7 +78,7 @@ const STATES = Object.freeze([
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
80
  'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
- ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
81
+ ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'early-final', 'human',
82
82
  ]);
83
83
 
84
84
  // A completed run with one of these conclusions does not make trunk red.
@@ -660,14 +660,43 @@ function decide(facts) {
660
660
  }
661
661
  const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
662
662
  add('regressions', reg.ok, reg.detail);
663
+ const per = f.period || { elapsed: false, detail: 'not measured' };
664
+ // #627: an early human final. On a route whose final is automatic (and not by an operator's grant —
665
+ // a granted deploy-tag final is already a human act whenever a human runs it), the test-period floor
666
+ // binds the MACHINE: a human who answers for the release (the bar: COLAB_HUMAN=1 + --answered-by,
667
+ // and --early, all three) may finalize the newest candidate before its period elapses. test-period
668
+ // is then reported, not required; trunk-green stays required over the part of the window that has
669
+ // elapsed (the CLI reads it up to now); every other check applies unchanged. --auto never carries
670
+ // the bar, so nothing an agent sets alone shortens a period.
671
+ let early = null;
672
+ if (h.early) {
673
+ const why = !h.bar ? 'needs the human bar (COLAB_HUMAN=1 + --answered-by)'
674
+ : finalMode !== 'auto' ? 'applies only where the final is automatic — here the final is already a human act, and the test period is not required of it'
675
+ : granted ? `applies only where the final is automatic by the row — here it is automatic only by the operator's grant (release.final-grant #${granted.issue}), so a human final already skips the period`
676
+ : s.older ? 'applies only to the newest open candidate — an older one is finalized only once its own period elapsed clean (#548)'
677
+ : null;
678
+ if (why) add('early-final', false, `--early ${why}`);
679
+ else {
680
+ const startMs = Date.parse(per.start);
681
+ const nowMs = Date.parse(f.now);
682
+ const elapsedHours = Number.isNaN(startMs) || Number.isNaN(nowMs) ? null : Math.max(0, Math.floor((nowMs - startMs) / 3600000));
683
+ const periodHours = Number(per.days) * 24;
684
+ early = { answeredBy: h.answeredBy, elapsedHours, periodHours, at: f.now || null };
685
+ add('early-final', true, per.elapsed
686
+ ? `--early by ${h.answeredBy}, but the ${per.days}d test period has already elapsed — an ordinary human final`
687
+ : `early human final, answered by ${h.answeredBy}: ${elapsedHours === null ? 'an unknown part' : `${elapsedHours}h`} of the ${periodHours}h test period elapsed — the floor binds the machine, not a person who answers for the release (CONVENTIONS.md §6)`);
688
+ auto = false;
689
+ }
690
+ }
663
691
  // #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
664
692
  // --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
665
693
  // no longer explains why THIS one, and its own clean period is what does.
666
694
  const ownClock = auto || !!s.older;
667
- const per = f.period || { elapsed: false, detail: 'not measured' };
668
- add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
695
+ add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : early && !per.elapsed ? `${per.detail} — reported, not required: an early human final (#627)` : per.detail, ownClock);
669
696
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
670
- add('trunk-green', tr.ok, tr.detail, ownClock);
697
+ // #627: an early final keeps trunk-green REQUIRED — over the elapsed part of the window.
698
+ const trunkRequired = ownClock || !!early;
699
+ add('trunk-green', tr.ok, early ? `${tr.detail} (the elapsed part of the window, up to the early final)` : tr.detail, trunkRequired);
671
700
  // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
672
701
  // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
673
702
  // those runs counted as passed; it is absent when no such run exists.
@@ -694,7 +723,7 @@ function decide(facts) {
694
723
  }
695
724
 
696
725
  if (held.length) return out('held');
697
- if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
726
+ if ((reg.permanent) || (trunkRequired && tr.permanent)) return out('needs-new-candidate');
698
727
  const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
699
728
  && !(c.condition === 'heavy-lane' && hv && hv.pending));
700
729
  if (blocking.length) return out('refused');
@@ -702,10 +731,14 @@ function decide(facts) {
702
731
  if (!tr.ok && !tr.pending) return out('refused');
703
732
  if (!per.elapsed || tr.pending) return out('testing');
704
733
  }
734
+ if (early) {
735
+ if (!tr.ok && !tr.pending) return out('refused');
736
+ if (tr.pending) return out('testing');
737
+ }
705
738
  if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
706
739
  if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
707
740
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
708
- return out('finalized', { finalTag: cand.version });
741
+ return out('finalized', { finalTag: cand.version, ...(early && !per.elapsed ? { early } : {}) });
709
742
  }
710
743
 
711
744
  // ---- announcing the final (#426) ----------------------------------------------------------------
@@ -742,8 +775,18 @@ function previousFinal(tagNames, version) {
742
775
  function releasedEvent(version) { return { released: version }; }
743
776
 
744
777
  /** The comment body posted on each carried issue (marker included) — codec `encodeReleasedComment`. */
745
- function releasedComment(version, sha) {
746
- return releaseCodec.encodeReleasedComment({ version, sha });
778
+ function releasedComment(version, sha, early = null) {
779
+ return releaseCodec.encodeReleasedComment({ version, sha, early });
780
+ }
781
+
782
+ /**
783
+ * #627: the one sentence an early human final is recorded with — on the tag, the tracking issue and
784
+ * every "Released in" comment: who answered, how much of the period had elapsed.
785
+ */
786
+ function earlyLine(early) {
787
+ const e = early || {};
788
+ const part = e.elapsedHours === null || e.elapsedHours === undefined ? 'an unknown part' : `${e.elapsedHours}h`;
789
+ return `answered by ${e.answeredBy} after ${part} of the ${e.periodHours}h test period${e.at ? ` (${e.at})` : ''} — a human final before the period elapsed (CONVENTIONS.md §6)`;
747
790
  }
748
791
 
749
792
  /** The final tag's annotated message: which candidate, which period, every condition, who. */
@@ -754,6 +797,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
754
797
  `Candidate: ${candidate.tag}`,
755
798
  `Commit: ${candidate.sha}`,
756
799
  period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
800
+ verdict.early ? `Early final: ${earlyLine(verdict.early)}` : null,
757
801
  `Finalized by: ${actor}`,
758
802
  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 final: human, revokes it)` : null,
759
803
  '',
@@ -767,6 +811,6 @@ module.exports = {
767
811
  parseVersion, compareVersions, parseCandidate,
768
812
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
769
813
  selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
770
- handoffCommand, decide, tagMessage, migrationGrantVerdict,
814
+ handoffCommand, decide, tagMessage, earlyLine, migrationGrantVerdict,
771
815
  carriedIssues, previousFinal, releasedEvent, releasedComment,
772
816
  };