@futurelastic/colab-handbook 1.13.0 → 1.14.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 (44) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +218 -53
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/templates/release-auto.yml +16 -3
  14. package/tools/colab +884 -98
  15. package/tools/lib/adopt.js +1 -1
  16. package/tools/lib/audit-cache.js +277 -0
  17. package/tools/lib/batch-stats.js +66 -43
  18. package/tools/lib/ci-cure.js +10 -1
  19. package/tools/lib/claim-comments.js +3 -2
  20. package/tools/lib/codec/decision.d.ts +7 -0
  21. package/tools/lib/codec/decision.js +54 -0
  22. package/tools/lib/codec/hold.d.ts +8 -1
  23. package/tools/lib/codec/hold.js +42 -8
  24. package/tools/lib/codec/release.js +6 -3
  25. package/tools/lib/codec/samples.json +45 -0
  26. package/tools/lib/config-set.js +4 -3
  27. package/tools/lib/cure-diff.js +27 -1
  28. package/tools/lib/decision-record.js +42 -0
  29. package/tools/lib/docs-only.js +47 -0
  30. package/tools/lib/git.js +57 -8
  31. package/tools/lib/grant-policy.js +133 -0
  32. package/tools/lib/instruction-file.js +75 -0
  33. package/tools/lib/instruction-gate.js +179 -0
  34. package/tools/lib/landed-prs.js +58 -0
  35. package/tools/lib/migration-grant.js +29 -5
  36. package/tools/lib/owner-policy.js +110 -0
  37. package/tools/lib/release-cut.js +127 -10
  38. package/tools/lib/release-finalize.js +66 -5
  39. package/tools/lib/ship-batch.js +188 -14
  40. package/tools/lib/ship-handoff.js +212 -0
  41. package/tools/lib/stamp.js +6 -2
  42. package/tools/lib/template-trunk.js +80 -0
  43. package/tools/lib/tree-green.js +21 -4
  44. package/tools/lib/workflow-triggers.js +57 -0
@@ -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,
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
77
77
 
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
- 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -379,6 +379,56 @@ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } =
379
379
  };
380
380
  }
381
381
 
382
+ // ---- a failed deploy job: a report on a human final, a gate on an automatic one (#565) -------------
383
+
384
+ // A job whose name says it deploys. The release workflow deploys the candidate to staging after it has
385
+ // built, tested and published it; that job's failure is about the deploy target (a host the runner
386
+ // cannot reach, a registry permission, a sibling image that was never built), never about the code.
387
+ const DEPLOY_JOB_RE = /\bdeploy/i;
388
+
389
+ /** Does a job named `name` deploy? Read from the name: GitHub's job read carries no environment. */
390
+ function isDeployJob(name) {
391
+ return DEPLOY_JOB_RE.test(String(name || ''));
392
+ }
393
+
394
+ /**
395
+ * The runs at a candidate's commit that failed ONLY in deploy jobs (#565). `rows` are the run rows
396
+ * (null = unread); `jobsOf(databaseId)` returns that run's jobs (`git.ghRunJobs`, null = unread), asked
397
+ * lazily and only for a completed run that concluded `failure`.
398
+ *
399
+ * A run is deploy-only when its jobs were read, at least one did not pass, and every job that did not
400
+ * pass (anything but success/skipped/neutral — cancelled included) is a deploy job. A job that builds,
401
+ * tests or publishes failing keeps the run a failure; so does a run whose jobs could not be read.
402
+ *
403
+ * Returns { rows, failures } — `rows` a copy of `rows` where each deploy-only run reads `success` and
404
+ * carries `deployFailed` (its failed deploy jobs), `failures` [{ workflowName, databaseId, jobs }] for
405
+ * the report. Measuring this never decides anything: decide() uses the rewritten reading only on a
406
+ * human final, and names the failures either way.
407
+ */
408
+ function deployOnlyFailures(rows, jobsOf) {
409
+ if (!Array.isArray(rows) || typeof jobsOf !== 'function') return { rows, failures: [] };
410
+ const failures = [];
411
+ const out = rows.map((r) => {
412
+ if (!r || r.status !== 'completed' || r.conclusion !== 'failure' || r.databaseId == null) return r;
413
+ const jobs = jobsOf(r.databaseId);
414
+ if (!Array.isArray(jobs) || !jobs.length) return r;
415
+ const bad = jobs.filter((j) => j && !(j.status === 'completed' && NOT_RED.has(j.conclusion)));
416
+ if (!bad.length || !bad.every((j) => isDeployJob(j.name))) return r;
417
+ const named = bad.map((j) => `${j.name} (${j.status === 'completed' ? j.conclusion || 'no conclusion' : j.status || 'unknown'})`);
418
+ failures.push({ workflowName: r.workflowName || '(unnamed workflow)', databaseId: r.databaseId, jobs: named });
419
+ return { ...r, conclusion: 'success', deployFailed: named };
420
+ });
421
+ return { rows: out, failures };
422
+ }
423
+
424
+ /** The `deploy-report` check's detail — what failed, and what it means on this final. */
425
+ function deployReportDetail(failures, { blocking }) {
426
+ const what = failures.map((f) => `${f.workflowName} run ${f.databaseId}: ${f.jobs.join(', ')}`).join('; ');
427
+ return blocking
428
+ ? `a deploy job failed at this candidate (${what}); an automatic final treats it as blocking, so ci-green, full-suite and cut-run read the run as failed`
429
+ : `a deploy job failed at this candidate (${what}); its build, tests and publish passed, so on a human final this is a report, not a gate: ci-green, full-suite and cut-run read that run without its deploy jobs. Check the deploy target before you finalize`;
430
+ }
431
+
382
432
  // ---- the test period ----------------------------------------------------------------------------
383
433
 
384
434
  /**
@@ -534,7 +584,8 @@ function handoffCommand(tag) {
534
584
  * `facts`:
535
585
  * policy release-policy.js evaluateRelease(doc)
536
586
  * selection selectCandidate(...)
537
- * tracking { number|null, createdAt|null, held, wouldCreate } | { error }
587
+ * tracking { number|null, title|null, createdAt|null, held, wouldCreate } | { error } — `title` is the
588
+ * matched issue's own, shown so a record that is not `release: vX.Y.Z` is visible (#575)
538
589
  * supersededHeld [issue numbers]
539
590
  * period periodVerdict(...) (when there is a candidate)
540
591
  * trunk trunkGreenVerdict(...)
@@ -586,7 +637,7 @@ function decide(facts) {
586
637
 
587
638
  const t = f.tracking || {};
588
639
  if (t.error) { add('tracking-issue', false, t.error); return out('refused'); }
589
- add('tracking-issue', true, t.number ? `#${t.number} (${trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
640
+ add('tracking-issue', true, t.number ? `#${t.number} (${t.title ? JSON.stringify(t.title) : trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
590
641
 
591
642
  const held = [...(t.held && t.number ? [t.number] : []), ...(f.supersededHeld || [])];
592
643
  add('release-hold', !held.length, held.length
@@ -616,7 +667,17 @@ function decide(facts) {
616
667
  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);
617
668
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
618
669
  add('trunk-green', tr.ok, tr.detail, ownClock);
619
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
670
+ // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
671
+ // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
672
+ // those runs counted as passed; it is absent when no such run exists.
673
+ const dr = f.deployReport && Array.isArray(f.deployReport.failures) && f.deployReport.failures.length ? f.deployReport : null;
674
+ const lenient = !!dr && !auto;
675
+ const pick = (strict, relaxed) => (lenient && relaxed ? relaxed : strict);
676
+ for (const [condition, v] of [['ci-green', pick(f.ci, dr && dr.ci)], ['full-suite', pick(f.suite, dr && dr.suite)], ['cut-run', pick(f.cutRun, dr && dr.cutRun)]]) {
677
+ add(condition, v && v.ok, v ? v.detail : 'not measured');
678
+ }
679
+ if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
680
+ for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
620
681
  add(condition, v && v.ok, v ? v.detail : 'not measured');
621
682
  }
622
683
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -698,7 +759,7 @@ module.exports = {
698
759
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
699
760
  parseVersion, compareVersions, parseCandidate,
700
761
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
701
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
762
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
702
763
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
703
764
  carriedIssues, previousFinal, releasedEvent, releasedComment,
704
765
  };
@@ -18,7 +18,11 @@
18
18
  * semantic conflicts need no shared file. The combined run is the gate.
19
19
  */
20
20
 
21
- const MAX_BATCH = 3;
21
+ // The SAFETY ceiling (#557): what any repo may declare, never what it gets. 3 until a red batch had
22
+ // a cheaper exit than N serial cycles; split-and-retry (nextStep's `split`) is that exit, so the
23
+ // ceiling is now 8 — the size from which bisection beats a serial fallback. A repo's own
24
+ // `ship-batch: <N>` is its ceiling; `ship-batch-steps` makes the size adapt below it.
25
+ const MAX_BATCH = 8;
22
26
  const REF_PREFIX = 'ship-batch/';
23
27
  // A concrete ref a `branches:` filter is tested against. Any 7-hex tail works: GitHub's filters see
24
28
  // the literal ref name, and the question is only whether `ship-batch/**` (or a wider glob) admits it.
@@ -26,7 +30,7 @@ const PROBE_REF = `${REF_PREFIX}0000000`;
26
30
  const TRAILER_KEY = 'Ship-Batch';
27
31
 
28
32
  /**
29
- * `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..3 → that
33
+ * `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..MAX_BATCH → that
30
34
  * (a single-digit string reads the same). Anything else — 0, 4, 2.5, true, a word — FAILS CLOSED to
31
35
  * serial, with the reason: a malformed opt-in must never widen what ship does. The audit fails the
32
36
  * same values.
@@ -39,19 +43,111 @@ function parseShipBatch(doc) {
39
43
  const v = doc['ship-batch'];
40
44
  // A digit string is accepted too: the audit's flat reader keeps every scalar a string, and the two
41
45
  // readers must agree on what is valid — a value one accepts and the other refuses is drift.
42
- const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9]$/.test(v.trim()) ? Number(v.trim()) : NaN);
46
+ const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9][0-9]*$/.test(v.trim()) ? Number(v.trim()) : NaN);
43
47
  if (Number.isInteger(n) && n >= 1 && n <= MAX_BATCH) {
44
48
  return { n, declared: true, valid: true, reason: `ship-batch: ${n}` };
45
49
  }
46
50
  return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
47
51
  }
48
52
 
53
+ const STEPS_KEY = 'ship-batch-steps';
54
+
55
+ /**
56
+ * #557: `ship-batch-steps:` from project.yml — the sizes an ADAPTIVE batch walks through, smallest
57
+ * first: grow one step after a green batch, shrink one after a red one. Written `2,4,8` (a YAML flow
58
+ * list `[2, 4, 8]` reads the same). Strictly ascending whole numbers within 1..`ship-batch` — the
59
+ * repo's own ceiling, which stays the largest a batch may ever be.
60
+ *
61
+ * Absent → `steps: null`: the size is fixed at `ship-batch`, today's behaviour exactly. The handbook
62
+ * gives NO default steps — the repo chooses them from its own `colab batch-stats`. Anything malformed
63
+ * FAILS CLOSED to `steps: null`, with the reason: the fixed size the repo already declared, never
64
+ * wider. The audit and the CI templates' descriptor check fail the same values.
65
+ */
66
+ function parseShipBatchSteps(doc) {
67
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, STEPS_KEY);
68
+ if (!has || doc[STEPS_KEY] === null || doc[STEPS_KEY] === undefined) {
69
+ return { steps: null, declared: false, valid: true, reason: `${STEPS_KEY} absent` };
70
+ }
71
+ const v = doc[STEPS_KEY];
72
+ const n = parseShipBatch(doc).n;
73
+ const bad = (why) => ({ steps: null, declared: true, valid: false, reason: `${STEPS_KEY} is ${JSON.stringify(v)}, ${why} (omit for a fixed size)` });
74
+ let parts;
75
+ if (Array.isArray(v)) parts = v.map((x) => String(x).trim());
76
+ else if (typeof v === 'number') parts = [String(v)];
77
+ else if (typeof v === 'string') parts = v.trim().replace(/^\[(.*)\]$/, '$1').split(',').map((x) => x.trim());
78
+ else return bad('expected ascending whole numbers like 2,4,8');
79
+ if (!parts.length || parts.some((x) => !/^[1-9][0-9]*$/.test(x))) return bad('expected ascending whole numbers like 2,4,8');
80
+ const steps = parts.map(Number);
81
+ if (steps.some((x, i) => i > 0 && x <= steps[i - 1])) return bad('expected strictly ascending sizes like 2,4,8');
82
+ if (steps[steps.length - 1] > n) return bad(`expected every size within ship-batch: ${n}, the repo's own ceiling`);
83
+ return { steps, declared: true, valid: true, reason: `${STEPS_KEY}: ${steps.join(',')}` };
84
+ }
85
+
86
+ /**
87
+ * #557: the trailer every batch head carries where steps are declared — the size the build TARGETED
88
+ * (not its fill), plus ` red` when the build is a split half of a red batch:
89
+ *
90
+ * Ship-Batch-Size: <s> built at step s
91
+ * Ship-Batch-Size: <s> red a split half; its parent batch, built at step s, went red
92
+ *
93
+ * It reaches trunk with a landed batch, so the next build reads the lane's last outcome from trunk
94
+ * alone — no batch state in ~/.colab, the same posture as memberTrailer.
95
+ */
96
+ const SIZE_TRAILER_KEY = 'Ship-Batch-Size';
97
+
98
+ function sizeTrailer({ size, red = false }) {
99
+ return `${SIZE_TRAILER_KEY}: ${size}${red ? ' red' : ''}`;
100
+ }
101
+
102
+ /** The LAST `Ship-Batch-Size:` trailer across commit messages → `{ size, red }`, else null. */
103
+ function parseSizeTrailer(messages) {
104
+ let out = null;
105
+ for (const msg of messages || []) {
106
+ for (const line of String(msg || '').split('\n')) {
107
+ const m = new RegExp(`^${SIZE_TRAILER_KEY}:\\s+([1-9][0-9]*)(\\s+red)?\\s*$`).exec(line.trim());
108
+ if (m) out = { size: Number(m[1]), red: !!m[2] };
109
+ }
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /**
115
+ * #557: the size the NEXT batch is built at.
116
+ * steps null (absent or malformed) → n, fixed — today's behaviour
117
+ * no trailer on trunk yet → the smallest step: a lane starts small and earns its width
118
+ * last landed batch green → the smallest step ABOVE its size (the largest step if none)
119
+ * last landed batch a red's half → the largest step BELOW its parent's size (the smallest if none)
120
+ * Never above n: parseShipBatchSteps already refuses a step above it.
121
+ */
122
+ function adaptiveSize({ n, steps, last }) {
123
+ if (!Array.isArray(steps) || !steps.length) return n;
124
+ if (!last || !Number.isFinite(last.size)) return steps[0];
125
+ if (last.red) {
126
+ const below = steps.filter((s) => s < last.size);
127
+ return below.length ? below[below.length - 1] : steps[0];
128
+ }
129
+ const above = steps.filter((s) => s > last.size);
130
+ return above.length ? above[0] : steps[steps.length - 1];
131
+ }
132
+
133
+ /**
134
+ * #557: split a red batch — the members (batch order) that form the FIRST half, tested next on the
135
+ * same base; the rest wait for the next batch. Sequential halves keep one batch per base, so the lane
136
+ * hold, the foreign-batch rule and the rebuild rule all hold unchanged; worst case for one culprit is
137
+ * about 2·log2(k)+1 cycles against 1+k for the serial fallback it replaces.
138
+ */
139
+ function splitHalves(members) {
140
+ const list = Array.isArray(members) ? members : [];
141
+ const cut = Math.ceil(list.length / 2);
142
+ return { first: list.slice(0, cut), held: list.slice(cut) };
143
+ }
144
+
49
145
  const WAIT_KEY = 'ship-batch-wait';
50
146
  const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
147
 
52
148
  /**
53
149
  * #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
54
- * before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
150
+ * before it lands alone (as a batch of one, #562). A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
55
151
  * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
152
  *
57
153
  * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
@@ -74,7 +170,8 @@ function parseShipBatchWait(doc) {
74
170
  }
75
171
 
76
172
  /**
77
- * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
173
+ * #555: does a batch call with ONE eligible member wait for a partner, or build now? (Past the window
174
+ * it lands alone — through the batch path, as a batch of one, #562 — never serially.)
78
175
  * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
176
  * already in flight — the lane is otherwise idle by then):
80
177
  * n parseShipBatch(doc).n
@@ -305,18 +402,26 @@ function combinedVerdict(rows) {
305
402
  /**
306
403
  * The one decision per `colab ship --batch` call. The command is RE-ENTRANT: it reads remote state,
307
404
  * takes one step, and exits — the caller waits (bounded, code-ship B1a) and calls again.
308
- * serial(reason) land nothing; hand the members back as a serial list (exit 4)
405
+ * serial(reason) land nothing; hand the members back as a serial list (exit 4) — never for
406
+ * a lone ready member: one member is a valid batch (#562)
309
407
  * wait-trunk trunk's own run is still in flight (exit 3)
310
408
  * rebuild a batch ref exists on a base trunk has moved past, or its members/heads are
311
409
  * no longer the ones asked for → delete it, then build afresh
312
410
  * build build + push the batch ref (exit 3)
313
411
  * wait-run the combined run is pending or has not appeared (exit 3)
314
- * red-rerun-or-serial combined run red on its FIRST attempt — the caller classifies it (§4): a
315
- * red:infra is re-run once, a red:finding goes serial (exit 4, ref kept)
316
- * red-serial red again after the one re-run — land nothing, serial (exit 4, ref deleted)
412
+ * red-rerun-or-split combined run red on its FIRST attempt, k > 1 members — the caller classifies
413
+ * it (§4): a red:infra is re-run once, a red:finding re-runs this command with
414
+ * `--split` (exit 4, ref kept) (#557)
415
+ * split red after the one re-run, or `--split` on a first-attempt red, k > 1 → rebuild
416
+ * the same ref with the first half of its members (splitHalves); the rest wait
417
+ * for the next batch (exit 3) (#557)
418
+ * red-rerun-or-serial a red batch of ONE on its first attempt: re-run once, or that member goes
419
+ * serial — it cannot split (exit 4, ref kept)
420
+ * red-serial a batch of one red after the re-run (or `--split`) — land nothing, serial
421
+ * (exit 4, ref deleted); that member returns to its implementer
317
422
  * land green → fast-forward trunk if it has not moved
318
423
  */
319
- function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null }) {
424
+ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null, split = false }) {
320
425
  if (!enabled) return { step: 'serial', reason: 'not-enabled' };
321
426
  if (!wired) return { step: 'serial', reason: 'unwired' };
322
427
  if (trunkCi === 'red') return { step: 'serial', reason: 'trunk-red' };
@@ -325,10 +430,18 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
325
430
  if (!trunkNow || !String(trunkNow).startsWith(existing.base7)) return { step: 'rebuild', reason: 'trunk-moved' };
326
431
  if (!existing.matches) return { step: 'rebuild', reason: 'members-changed' };
327
432
  if (!verdict || verdict.state === 'pending' || verdict.state === 'none') return { step: 'wait-run' };
328
- if (verdict.state === 'red') return verdict.attempt >= 2 ? { step: 'red-serial' } : { step: 'red-rerun-or-serial' };
433
+ if (verdict.state === 'red') {
434
+ // #557: a red batch of k > 1 splits instead of going serial. After its one re-run, it splits by
435
+ // itself; on the first attempt the caller has classified it (red:finding → `--split`).
436
+ const k = Array.isArray(existing.members) ? existing.members.length : 1;
437
+ if (verdict.attempt >= 2 || split) return k > 1 ? { step: 'split' } : { step: 'red-serial' };
438
+ return k > 1 ? { step: 'red-rerun-or-split' } : { step: 'red-rerun-or-serial' };
439
+ }
329
440
  return { step: 'land' };
330
441
  }
331
- if (eligibleCount < 2) return { step: 'serial', reason: 'too-few' };
442
+ // #562: a batch of ONE is a batch — a lone ready member still lands through the combined run, so
443
+ // the setups a repo runs only on ship-batch/** and trunk gate it before trunk moves.
444
+ if (eligibleCount < 1) return { step: 'serial', reason: 'none-ready' };
332
445
  return { step: 'build' };
333
446
  }
334
447
 
@@ -366,6 +479,66 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
366
479
  return (batchRows || []).length >= a.length;
367
480
  }
368
481
 
482
+ /**
483
+ * #581: the lane reservation. A batch ref at trunk's CURRENT tip whose combined run is in flight (or
484
+ * green and not yet landed) holds the trunk lane: a serial `colab ship` into trunk that landed now
485
+ * would move trunk under it, and the batch's next call would throw the green run away and rebuild —
486
+ * measured five builds in two hours on one repo, every member ready the whole time. The ref itself
487
+ * is the reservation: it already sits on the remote every lander reads, it names its base, and its
488
+ * runs say whether it is alive. No second record to write, expire or keep in sync.
489
+ *
490
+ * Facts in, per batch ref on the remote (`batches`):
491
+ * ref, base7 parseBatchRef
492
+ * verdict combinedVerdict of the runs at its head
493
+ * builtAtMs the batch head's commit time (the build commits it), null = unread
494
+ * settledAtMs the newest `updatedAt` of its runs once green, null = unread
495
+ * plus `trunkNow` (the remote trunk sha), `nowMs`, and `graceSec`.
496
+ *
497
+ * Out: `{ held: true, ref, why }` for the first batch that holds the lane, else `{ held: false,
498
+ * released: [{ ref, why }] }` naming each batch at this base that does NOT hold it, and why.
499
+ * - a batch on an older base holds nothing: trunk already moved past it, it rebuilds anyway;
500
+ * - red (first attempt or after its re-run) → declined, holds nothing;
501
+ * - pending, or a run list that could not be read → held (fail closed: a pause clears itself);
502
+ * - no run yet → held for `graceSec` after it was built, then released (its run never came);
503
+ * - green → held for `graceSec` after it went green — its lander lands it on its next call —
504
+ * then released: a green batch nobody lands is abandoned, and must not hold the lane forever.
505
+ * An unread time (built/settled) is released, never held: a hold has to be provably alive.
506
+ */
507
+ const LANE_GRACE_SEC = 900;
508
+
509
+ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {}) {
510
+ const now = String(trunkNow || '');
511
+ const released = [];
512
+ if (!now) return { held: false, released };
513
+ const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
514
+ const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
515
+ for (const b of (Array.isArray(batches) ? batches : [])) {
516
+ if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
517
+ const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
518
+ if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
519
+ if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
520
+ if (v.state === 'none') {
521
+ if (fresh(b.builtAtMs)) return { held: true, ref: b.ref, why: `built ${mins(b.builtAtMs)}, its combined run has not appeared yet` };
522
+ released.push({ ref: b.ref, why: Number.isFinite(b.builtAtMs)
523
+ ? `no combined run ${mins(b.builtAtMs)} after it was built (grace ${graceSec}s) — treated as abandoned`
524
+ : 'no combined run, and its build time could not be read — not provably alive' });
525
+ continue;
526
+ }
527
+ if (fresh(b.settledAtMs)) return { held: true, ref: b.ref, why: `combined run green ${mins(b.settledAtMs)} — its lander lands it on its next call` };
528
+ released.push({ ref: b.ref, why: Number.isFinite(b.settledAtMs)
529
+ ? `combined run green ${mins(b.settledAtMs)} and still not landed (grace ${graceSec}s) — treated as abandoned`
530
+ : 'combined run green, but when it went green could not be read — not provably alive' });
531
+ }
532
+ return { held: false, released };
533
+ }
534
+
535
+ /** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
536
+ function settledAt(rows) {
537
+ const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
538
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
539
+ return t.length ? Math.max(...t) : null;
540
+ }
541
+
369
542
  /**
370
543
  * #415: branches the command line names that a staged batch does not carry, in command-line order.
371
544
  * `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
@@ -421,9 +594,10 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
421
594
  }
422
595
 
423
596
  module.exports = {
424
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
425
- parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
597
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, STEPS_KEY, SIZE_TRAILER_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
598
+ parseShipBatch, parseShipBatchWait, parseShipBatchSteps, sizeTrailer, parseSizeTrailer, adaptiveSize, splitHalves, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
426
599
  droppedTrailer, parseDroppedTrailers, appendTrailers,
427
600
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
428
601
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
602
+ LANE_GRACE_SEC, laneHold, settledAt,
429
603
  };