@futurelastic/colab-handbook 1.14.0-rc.15 → 1.14.0-rc.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -122,6 +122,7 @@ const installRoute = require("../tools/lib/install-route.js");
122
122
  const releaseRunner = require("../tools/lib/release-runner.js"); // #453
123
123
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
124
124
  const shipBatch = require("../tools/lib/ship-batch.js");
125
+ const integrationProfile = require("../tools/lib/integration-profile.js"); // #610
125
126
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
126
127
  const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
127
128
  const batchHistory = require("../tools/lib/batch-history.js"); // #556
@@ -1771,6 +1772,31 @@ function auditRepoInner(target, ctx) {
1771
1772
  }
1772
1773
  }
1773
1774
 
1775
+ // ---- integration-profile / heavy-workflow (#610) ---------------------------
1776
+ // Read through tools/lib/integration-profile.js — the module `colab ship` and `colab release` use,
1777
+ // so the audit and the gates cannot disagree about a value. A malformed value makes the gates fail
1778
+ // closed to release-heavy (ship unchanged), which is safe but silent, so it fails here. The `live`
1779
+ // restriction fails only a DECLARED qualify/release-heavy; a repo that never declared gets a
1780
+ // suggestion, never a new failure.
1781
+ let integrationSuggestion = null;
1782
+ if (cfg) {
1783
+ const ipCfg = integrationProfile.parseProfile(cfg);
1784
+ const hwCfg = integrationProfile.parseHeavyWorkflow(cfg);
1785
+ if (!ipCfg.valid) fail(`${ipCfg.reason} — see project.schema.md, integration-profile`);
1786
+ if (!hwCfg.valid) fail(`${hwCfg.reason} — see project.schema.md, heavy-workflow`);
1787
+ if (ipCfg.valid) {
1788
+ const lr = integrationProfile.liveRestriction({ profile: ipCfg.profile, declared: ipCfg.declared, exposure: authority ? authority.exposure : null, deploy });
1789
+ if (lr && lr.level === "fail") fail(lr.message);
1790
+ else if (lr) integrationSuggestion = lr.message;
1791
+ if (ipCfg.profile === "promote" && (!trunk || trunk === "main")) {
1792
+ fail(`integration-profile: promote gates the promotion into main with the heavy lane, but trunk is ${JSON.stringify(trunk)} — there is no promotion to gate. Choose gated, qualify or release-heavy (CONVENTIONS.md §7, Integration profiles)`);
1793
+ }
1794
+ if (ipCfg.profile === "gated" && hwCfg.valid && !workflows.includes(hwCfg.file)) {
1795
+ warn(`integration-profile: gated but no .github/workflows/${hwCfg.file} — colab ship refuses every code landing until a heavy lane exists (templates/ci-<stack>-heavy.yml), or name it with heavy-workflow:`);
1796
+ }
1797
+ }
1798
+ }
1799
+
1774
1800
  // Additive `--json` keys only (#144's oracle: "`tier` continues to report the DECLARED
1775
1801
  // letter... New keys are additive"). `axisOfRecord` names which key governs
1776
1802
  // ('exposure' | 'tier-legacy' | 'none' | null when project.yml itself did not parse);
@@ -2108,6 +2134,7 @@ function auditRepoInner(target, ctx) {
2108
2134
  info.predatesAxes = [];
2109
2135
  info.suggestions = [];
2110
2136
  const suggest = (t) => info.suggestions.push(t);
2137
+ if (integrationSuggestion) suggest(integrationSuggestion); // #610
2111
2138
  if (!isSelf) checkStamps(src, ctx.handbook, ctx.templateNames, fail, warn, { ceremony, missingAxes, predatesAxes: info.predatesAxes, writesRaw, suggest });
2112
2139
 
2113
2140
  // ---- repository metadata identity scan (#228 part 4) ----------------------
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.15"
36
+ "version": "1.14.0-rc.16"
37
37
  }
@@ -42,8 +42,23 @@ or warn. The handbook enforces only what `colab ship` reads from your CI
42
42
  suppresses a new one. If the issue list cannot be read, it files nothing and fails the job.
43
43
  - **Exposure sets the bar.** `live`/`released` repos run the heavy lane before every official
44
44
  build. `none`/`self` repos may run it nightly only.
45
- - **The trade-off:** a defect the light lane misses can sit on trunk for up to a day. Where a
46
- merge queue and spare runners exist, a full run per batch is an optional third trigger.
45
+ - **The trade-off:** a defect the light lane misses can sit on trunk for up to a day. A repo that
46
+ cannot accept that picks another `integration-profile:` (below).
47
+
48
+ ### Where each integration profile wires the heavy lane (#610)
49
+
50
+ `integration-profile:` in `project.yml` ([CONVENTIONS §7](../CONVENTIONS.md#integration-profiles--where-the-heavy-lane-runs-and-what-a-green-trunk-promises-610))
51
+ decides when the heavy lane runs. The light `ci.yml` is the same under every profile; only the heavy
52
+ file's triggers change:
53
+
54
+ | Profile | What to change in `ci-heavy.yml` |
55
+ |---|---|
56
+ | `release-heavy` (absent) | nothing — the template as copied: nightly, plus every official build |
57
+ | `gated` | nothing — `colab ship` dispatches it (`workflow_dispatch`, input `ref` = the sha) at each landing's branch or batch head, and lands only on its green. Keep `workflow_dispatch` and its `ref` input. |
58
+ | `qualify` | the `schedule` cron becomes the clock: every few hours on trunk's tip (e.g. `"23 */4 * * *"`), still skipped when trunk has not moved |
59
+ | `promote` | dispatch it on the trunk tip before `colab promote` (`gh workflow run ci-heavy.yml --ref dev -f ref=<sha>`) — promote refuses until it is green |
60
+
61
+ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `project.yml`.
47
62
  - **Traps the heavy template already handles:**
48
63
  - It has no push or `pull_request` trigger, so ship never counts its run.
49
64
  - The `plan` job, not an all-skipped run, is what concludes `success` on a skipped nightly.
@@ -14,6 +14,10 @@
14
14
  # green; release-auto.yml dispatches it at each candidate and finalizes only when it is
15
15
  # green at that exact sha.
16
16
  # - BY HAND: Actions → "CI (heavy)" → Run workflow, with a ref.
17
+ # - Per INTEGRATION PROFILE (project.yml `integration-profile:`, #610): `gated` — colab ship
18
+ # dispatches this file at each landing and lands only on its green (keep workflow_dispatch and
19
+ # its `ref` input); `qualify` — make the cron below a clock, every few hours; `promote` —
20
+ # dispatch it on trunk's tip before colab promote. Absent = release-heavy: as copied.
17
21
  # Heavy is opt-in per test; an unmarked test is light. The marker:
18
22
  # the Pest/PHPUnit group `heavy` (`->group('heavy')`, `#[Group('heavy')]`). The light
19
23
  # lane excludes it; this lane runs the whole suite.
@@ -14,6 +14,10 @@
14
14
  # green; release-auto.yml dispatches it at each candidate and finalizes only when it is
15
15
  # green at that exact sha.
16
16
  # - BY HAND: Actions → "CI (heavy)" → Run workflow, with a ref.
17
+ # - Per INTEGRATION PROFILE (project.yml `integration-profile:`, #610): `gated` — colab ship
18
+ # dispatches this file at each landing and lands only on its green (keep workflow_dispatch and
19
+ # its `ref` input); `qualify` — make the cron below a clock, every few hours; `promote` —
20
+ # dispatch it on trunk's tip before colab promote. Absent = release-heavy: as copied.
17
21
  # Heavy is opt-in per test; an unmarked test is light. The marker:
18
22
  # a `test:heavy` script in package.json (e.g. over `*.heavy.test.*` files). `npm test`
19
23
  # stays light; this lane runs both.
@@ -14,6 +14,10 @@
14
14
  # green; release-auto.yml dispatches it at each candidate and finalizes only when it is
15
15
  # green at that exact sha.
16
16
  # - BY HAND: Actions → "CI (heavy)" → Run workflow, with a ref.
17
+ # - Per INTEGRATION PROFILE (project.yml `integration-profile:`, #610): `gated` — colab ship
18
+ # dispatches this file at each landing and lands only on its green (keep workflow_dispatch and
19
+ # its `ref` input); `qualify` — make the cron below a clock, every few hours; `promote` —
20
+ # dispatch it on trunk's tip before colab promote. Absent = release-heavy: as copied.
17
21
  # Heavy is opt-in per test; an unmarked test is light. The marker:
18
22
  # the pytest marker `heavy` (`@pytest.mark.heavy`, registered in pytest.ini or
19
23
  # pyproject.toml). The light lane deselects it; this lane runs everything.
package/tools/colab CHANGED
@@ -70,6 +70,7 @@ const shipBatch = require('./lib/ship-batch');
70
70
  const batchStats = require('./lib/batch-stats');
71
71
  const conflictMarkers = require('./lib/conflict-markers');
72
72
  const docsOnly = require('./lib/docs-only');
73
+ const integrationProfile = require('./lib/integration-profile');
73
74
  const secretScan = require('./lib/secret-scan'); // #606
74
75
  const configSet = require('./lib/config-set'); // #561
75
76
  const cureDiff = require('./lib/cure-diff');
@@ -1710,8 +1711,17 @@ function cmdReleaseCut(argv) {
1710
1711
  }
1711
1712
  }
1712
1713
 
1714
+ // #610: on a final route the heavy lane must be green at this sha. Under --auto (the release
1715
+ // workflow) a missing run is started here, once, and the run no-ops until it is green.
1716
+ let heavy = null;
1717
+ if (fast || library) {
1718
+ const lane = heavyLaneAt(repoAbs, doc, sha);
1719
+ heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
1720
+ if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1721
+ }
1722
+
1713
1723
  const verdict = releaseCut.decide({
1714
- policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
1724
+ policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
1715
1725
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1716
1726
  finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1717
1727
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
@@ -1996,6 +2006,16 @@ function readRegressionEdges(repoAbs, num) {
1996
2006
  }
1997
2007
  }
1998
2008
 
2009
+ /**
2010
+ * #610: the heavy lane at a release candidate, as release-finalize.js decide()'s `heavy` fact. Read
2011
+ * the same way ship's gated landing reads it (heavyLaneAt). Inside the release workflow the heavy
2012
+ * lane is a separate workflow, never the one running, so #425's own-workflow filter does not apply.
2013
+ */
2014
+ function releaseHeavyFact(repoAbs, doc, cand) {
2015
+ const lane = heavyLaneAt(repoAbs, doc, cand.sha);
2016
+ return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
2017
+ }
2018
+
1999
2019
  function cmdReleaseFinalize(argv) {
2000
2020
  const opts = parseArgs(argv, {
2001
2021
  values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
@@ -2138,6 +2158,7 @@ function cmdReleaseFinalize(argv) {
2138
2158
  const verdict = releaseFinalize.decide({
2139
2159
  policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
2140
2160
  ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2161
+ heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
2141
2162
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2142
2163
  human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2143
2164
  });
@@ -10650,6 +10671,10 @@ Sequence (each step gated; any failure aborts before the push — the target is
10650
10671
  and worktree untouched. Re-run the same command once an account other than the
10651
10672
  author approved the branch's CURRENT head: it lands by the ordinary squash below
10652
10673
  and closes the PR. Accounts sharing one login cannot approve each other.
10674
+ b5. heavy lane (#610) only with integration-profile: gated, never for a docs-only change:
10675
+ the heavy workflow (heavy-workflow:, default ci-heavy.yml) green at the
10676
+ branch's remote head. None yet → a real ship dispatches it and PAUSES —
10677
+ "⏸ HEAVY-PENDING", exit 3, nothing merged; running → the same pause; red → ✗.
10653
10678
  c. B0 sync merge the target INTO the branch; non-generated conflict → abort (human merge);
10654
10679
  generated-only conflict → repo's .colab/hooks/pre-ship regenerates, else abort
10655
10680
  d. B1 squash re-check CI green, then squash-merge branch → target (Closes every claimed issue,
@@ -12582,6 +12607,14 @@ function cmdShipDryJson(opts) {
12582
12607
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
12583
12608
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
12584
12609
  }
12610
+ // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
12611
+ // its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
12612
+ const heavyJson = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCiJson.applies, batchMember: !!opts._batchMember });
12613
+ if (heavyJson) {
12614
+ checks.push({ name: 'heavy lane green (integration-profile: gated, #610)', ok: heavyJson.ok,
12615
+ class: heavyJson.ok ? null : (heavyJson.action === 'refuse' ? HUMAN_GATED : SELF_CLEARING),
12616
+ action: heavyJson.action, detail: heavyJson.detail });
12617
+ }
12585
12618
 
12586
12619
  // #350: same single producer as the prose path. 'pending' is not a failure — it is `mode`.
12587
12620
  const coreReviewJson = shipCoreReview(repoAbs, gh, target, sess.branch);
@@ -13768,6 +13801,12 @@ function cmdShip(argv) {
13768
13801
  } else {
13769
13802
  checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
13770
13803
  }
13804
+ // #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
13805
+ // heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
13806
+ // heavy lane at all, fails the table.
13807
+ const heavyGate = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCi.applies });
13808
+ if (heavyGate) checks.push([heavyGate.ok ? '✓' : (heavyGate.action === 'refuse' ? '✗' : '⏸'), 'heavy lane green (integration-profile: gated, #610)', heavyGate.detail]);
13809
+ const heavyOk = !heavyGate || heavyGate.action !== 'refuse';
13771
13810
 
13772
13811
  // #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
13773
13812
  // taken below once every real precondition has passed, so it is the ONLY thing between the branch
@@ -13793,7 +13832,7 @@ function cmdShip(argv) {
13793
13832
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
13794
13833
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
13795
13834
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
13796
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk;
13835
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
13797
13836
 
13798
13837
  // ---- report the table ----
13799
13838
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -14016,6 +14055,8 @@ function cmdShip(argv) {
14016
14055
  print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
14017
14056
  } else if (lane && lane.held && coreReview.verdict !== 'pending') {
14018
14057
  print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
14058
+ } else if (heavyGate && !heavyGate.ok && coreReview.verdict !== 'pending') {
14059
+ print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${heavyGate.action === 'dispatch' ? `a real ship dispatches ${heavyGate.file} at ${shortSha(heavyGate.sha)}` : 'the heavy lane is not green yet'} (integration-profile: gated, #610); run again once it is green`);
14019
14060
  } else if (coreReview.verdict === 'pending') {
14020
14061
  print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
14021
14062
  'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
@@ -14084,6 +14125,14 @@ function cmdShip(argv) {
14084
14125
  // ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
14085
14126
  if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
14086
14127
 
14128
+ // ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
14129
+ if (heavyGate && !heavyGate.ok) {
14130
+ print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
14131
+ if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
14132
+ else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
14133
+ return 3;
14134
+ }
14135
+
14087
14136
  // ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
14088
14137
  const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
14089
14138
  const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
@@ -14850,6 +14899,58 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
14850
14899
  }
14851
14900
 
14852
14901
  /** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
14902
+ /**
14903
+ * #610: the heavy lane at one sha — which workflow it is, whether the tree there has it, and its
14904
+ * verdict. The heavy workflow is named by FILE (`heavy-workflow:`, default ci-heavy.yml); its run
14905
+ * rows carry the workflow's `name:`, so the file at that sha is read to learn which rows are heavy.
14906
+ * `rows: null` (gh unreadable) stays `unread` — never "no heavy run", which would dispatch.
14907
+ */
14908
+ function heavyLaneAt(repoAbs, doc, sha) {
14909
+ const file = integrationProfile.parseHeavyWorkflow(doc).file;
14910
+ const rel = `.github/workflows/${file}`;
14911
+ let present = false, name = rel;
14912
+ if (sha) {
14913
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
14914
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
14915
+ if (show.ok) {
14916
+ present = true;
14917
+ const t = verifyRuns.workflowTriggers(show.stdout);
14918
+ if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
14919
+ }
14920
+ }
14921
+ const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
14922
+ const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
14923
+ return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
14924
+ }
14925
+
14926
+ /**
14927
+ * #610: `integration-profile: gated` — a serial landing waits on a green heavy run at the branch's
14928
+ * remote head. Null under every other profile (ship reads the light lane, as before), for a docs-only
14929
+ * change (no CI wait at all, #606), and for a batch member read (the batch head is graded instead).
14930
+ */
14931
+ function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMember = false } = {}) {
14932
+ const profile = integrationProfile.parseProfile(doc).profile;
14933
+ if (profile !== 'gated' || docsOnlyApplies || batchMember) return null;
14934
+ const refs = git.branchRefs(repoAbs, branch);
14935
+ const sha = refs.remoteSha || null;
14936
+ const at = sha ? `${branch}@${shortSha(sha)}` : branch;
14937
+ if (!sha) return { ok: false, action: 'wait', detail: `integration-profile: gated — ${branch} is not on the remote yet, so the heavy lane cannot run at its head (push it)`, sha: null, file: null };
14938
+ if (refs.localSha && refs.localSha !== sha && !git.git(['merge-base', '--is-ancestor', refs.localSha, sha], repoAbs).ok) {
14939
+ return { ok: false, action: 'wait', detail: `integration-profile: gated — local ${branch} has commits the remote head ${shortSha(sha)} does not; the heavy lane would test the wrong code (push it)`, sha: null, file: null };
14940
+ }
14941
+ const lane = heavyLaneAt(repoAbs, doc, sha);
14942
+ const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
14943
+ return { ...gate, sha, file: lane.file, name: lane.name };
14944
+ }
14945
+
14946
+ /** #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits. */
14947
+ function dispatchHeavyLane(repoAbs, file, ref, sha) {
14948
+ const d = git.ghWorkflowDispatch(repoAbs, file, ref, { ref: sha });
14949
+ if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
14950
+ else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: gh workflow run ${file} --ref ${ref} -f ref=${sha}`);
14951
+ return d.ok;
14952
+ }
14953
+
14853
14954
  function printBatchLanePause(lane, trunk) {
14854
14955
  print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
14855
14956
  print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
@@ -15097,7 +15198,20 @@ function cmdShipBatch(opts) {
15097
15198
  }
15098
15199
  }
15099
15200
  }
15100
- const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15201
+ let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
15202
+ // #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
15203
+ // heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
15204
+ // the same re-run / split path a light red does, and the split walks toward the culprit.
15205
+ let heavyWave = null;
15206
+ if (verdict && integrationProfile.parseProfile(doc).profile === 'gated') {
15207
+ heavyWave = heavyLaneAt(repoAbs, doc, existing.sha);
15208
+ if (!heavyWave.present) {
15209
+ print(`✗ ship-batch: integration-profile: gated, but no .github/workflows/${heavyWave.file} at ${existing.ref}@${shortSha(existing.sha)} — a wave lands only on a green heavy run, and there is no heavy lane to run. Nothing landed.`);
15210
+ print(' Add one: `colab template ci-<stack>-heavy --dest .github/workflows/ci-heavy.yml` (or name yours with heavy-workflow:), land it, then re-run once it is on trunk.');
15211
+ return 4;
15212
+ }
15213
+ verdict = integrationProfile.waveVerdict(verdict, heavyWave.verdict);
15214
+ }
15101
15215
  // #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
15102
15216
  let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
15103
15217
  J.step = step.step;
@@ -15114,6 +15228,7 @@ function cmdShipBatch(opts) {
15114
15228
  }
15115
15229
  if (step.step === 'wait-run') {
15116
15230
  print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
15231
+ if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
15117
15232
  print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
15118
15233
  return 3;
15119
15234
  }
@@ -16867,6 +16982,23 @@ function cmdPromote(argv) {
16867
16982
  else checks.push(['✗', 'trunk CI green', `${trunk}@${shortSha(run.sha)}: status=${run.status} conclusion=${run.conclusion || 'none'} (fail-to-start counts as not green)`]);
16868
16983
  }
16869
16984
 
16985
+ // #610: integration-profile: promote — the heavy lane gates the promotion: green at the exact sha
16986
+ // being promoted (origin's trunk tip). Never dispatched from here: promotion is a human act, and
16987
+ // the command to start the heavy lane is printed instead.
16988
+ let heavyOk = true;
16989
+ if (integrationProfile.parseProfile(doc).profile === 'promote') {
16990
+ const tipR = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16991
+ const tip = tipR.ok ? tipR.stdout : null;
16992
+ const lane = tip ? heavyLaneAt(repoAbs, doc, tip) : null;
16993
+ const at = tip ? `${trunk}@${shortSha(tip)}` : trunk;
16994
+ let detail;
16995
+ if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
16996
+ else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
16997
+ else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
16998
+ else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: gh workflow run ${lane.file} --ref ${trunk} -f ref=${tip}` : ''}`; }
16999
+ checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
17000
+ }
17001
+
16870
17002
  const localTrunk = git.git(['rev-parse', trunk], repoAbs);
16871
17003
  const originTrunk = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
16872
17004
  const trunkSyncOk = localTrunk.ok && originTrunk.ok && localTrunk.stdout === originTrunk.stdout;
@@ -16896,7 +17028,7 @@ function cmdPromote(argv) {
16896
17028
  ahead > 0 ? `${ahead} commit(s) to promote` : `could not count ${remote}/${MAIN}..${remote}/${trunk}`]);
16897
17029
  }
16898
17030
 
16899
- const preOk = ciOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
17031
+ const preOk = ciOk && heavyOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
16900
17032
 
16901
17033
  // ---- report ----
16902
17034
  say(`promote ${shortRepo(repoAbs)} · ${trunk} → ${MAIN}` + (opts.dry ? ' [DRY RUN]' : ''));
@@ -0,0 +1,161 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/integration-profile.js — where a repo's heavy CI lane runs, and what a green trunk
4
+ * promises (#610). The pure half: project.yml in, a profile and verdicts out. No git, no gh.
5
+ *
6
+ * #607 split CI into a light lane (every push; the lane `colab ship` reads) and a heavy lane (the
7
+ * whole suite, e2e, load: nightly and at every official build). That is ONE shape. Some repos cannot
8
+ * accept a trunk that is only light-green between releases; others want the heavy lane more often
9
+ * than at release. `integration-profile:` makes the shape a declared choice:
10
+ *
11
+ * gated every landing waits on a green heavy run at the candidate's exact sha
12
+ * (the branch head, or the batch head under `colab ship --batch`). Trunk is
13
+ * always heavy-green.
14
+ * qualify ship reads the light lane only; the heavy lane runs on trunk on a clock (the
15
+ * heavy workflow's cron), plus nightly and at the release gate. Trunk may be heavy-
16
+ * red for at most one clock window; a red is reverted first.
17
+ * release-heavy #607's shape and the DEFAULT when the key is absent: light per merge, heavy
18
+ * nightly and at the official build.
19
+ * promote a `develop → main` repo: the heavy lane gates the promotion. Kept for repos that
20
+ * already run it for an approval gate; not offered to new repos.
21
+ *
22
+ * Under EVERY profile a final release needs the heavy lane green at the candidate's sha, wherever the
23
+ * repo has a heavy lane at all (release-finalize.js `heavy-lane`).
24
+ *
25
+ * The heavy lane is found by its workflow FILE (`heavy-workflow:`, default `ci-heavy.yml` — the name
26
+ * #607's templates give it, and the name release-auto.yml already dispatches by). Run rows carry the
27
+ * workflow's `name:`, not its file, so the caller reads the file at the sha to learn which rows are
28
+ * heavy (`tools/colab` heavyWorkflowNameAt).
29
+ *
30
+ * FAIL CLOSED, like parseShipBatch: a malformed value reads as the default (`release-heavy`, ship
31
+ * unchanged) and the audit fails it. A typo must never silently weaken a declared `gated` — but it
32
+ * cannot strengthen anything either, and the audit is where a broken descriptor is reported.
33
+ */
34
+
35
+ const KEY = 'integration-profile';
36
+ const HEAVY_KEY = 'heavy-workflow';
37
+ const PROFILES = Object.freeze(['gated', 'qualify', 'release-heavy', 'promote']);
38
+ const DEFAULT_PROFILE = 'release-heavy';
39
+ const DEFAULT_HEAVY_WORKFLOW = 'ci-heavy.yml';
40
+
41
+ function hasKey(doc, key) {
42
+ return !!doc && Object.prototype.hasOwnProperty.call(doc, key) && doc[key] !== null && doc[key] !== undefined && doc[key] !== '';
43
+ }
44
+
45
+ /** `{ profile, declared, valid, reason }` — absent → release-heavy, undeclared; bad → release-heavy, invalid. */
46
+ function parseProfile(doc) {
47
+ if (!hasKey(doc, KEY)) return { profile: DEFAULT_PROFILE, declared: false, valid: true, reason: `${KEY} absent (${DEFAULT_PROFILE})` };
48
+ const raw = doc[KEY];
49
+ const v = typeof raw === 'string' ? raw.trim() : raw;
50
+ if (typeof v === 'string' && PROFILES.includes(v)) return { profile: v, declared: true, valid: true, reason: `${KEY}: ${v}` };
51
+ return { profile: DEFAULT_PROFILE, declared: true, valid: false,
52
+ reason: `${KEY} is ${JSON.stringify(raw)}, expected one of ${PROFILES.join(' | ')} (omit for ${DEFAULT_PROFILE})` };
53
+ }
54
+
55
+ /** `{ file, declared, valid, reason }` — a bare workflow file name under .github/workflows. */
56
+ function parseHeavyWorkflow(doc) {
57
+ if (!hasKey(doc, HEAVY_KEY)) return { file: DEFAULT_HEAVY_WORKFLOW, declared: false, valid: true, reason: `${HEAVY_KEY} absent (${DEFAULT_HEAVY_WORKFLOW})` };
58
+ const raw = doc[HEAVY_KEY];
59
+ const v = typeof raw === 'string' ? raw.trim() : '';
60
+ if (/^[A-Za-z0-9._-]+\.ya?ml$/.test(v)) return { file: v, declared: true, valid: true, reason: `${HEAVY_KEY}: ${v}` };
61
+ return { file: DEFAULT_HEAVY_WORKFLOW, declared: true, valid: false,
62
+ reason: `${HEAVY_KEY} is ${JSON.stringify(raw)}, expected a workflow file name in .github/workflows (e.g. ${DEFAULT_HEAVY_WORKFLOW})` };
63
+ }
64
+
65
+ /**
66
+ * The heavy lane's verdict at one sha, from the rows of that workflow at that sha
67
+ * (`{status, conclusion}`). Same all-runs reading as ship's: any finished not-green row (cancelled
68
+ * aside) is red; any unfinished row is pending; green needs a success. A red re-run green later is
69
+ * still red here only while the red row is the newest — callers pass the newest attempt's rows.
70
+ * null rows → `unread` (the run list could not be read — never "none")
71
+ */
72
+ function heavyVerdict(rows) {
73
+ if (!Array.isArray(rows)) return { state: 'unread', why: 'the run list could not be read' };
74
+ if (!rows.length) return { state: 'none', why: 'no heavy run at this sha' };
75
+ // A re-run is the same run with a higher attempt; separate dispatches are separate rows. The newest
76
+ // dispatch speaks for the sha (a red then a green re-dispatch is green), so read the newest row.
77
+ const newest = rows.slice().sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')))[0];
78
+ const ref = newest.url || (newest.databaseId !== undefined && newest.databaseId !== null ? `run ${newest.databaseId}` : null);
79
+ if (newest.status !== 'completed') return { state: 'pending', why: `the heavy run is ${newest.status || 'in flight'}`, url: ref };
80
+ if (newest.conclusion === 'success') return { state: 'green', why: 'the heavy run succeeded', url: ref };
81
+ if (newest.conclusion === 'cancelled') return { state: 'none', why: 'the newest heavy run was cancelled', url: ref };
82
+ return { state: 'red', why: `the heavy run finished ${newest.conclusion || 'without a conclusion'}`, url: ref };
83
+ }
84
+
85
+ /**
86
+ * #610's one restriction: on exposure `live` the promotion deploys, so a trunk that may be heavy-red
87
+ * (qualify, release-heavy) must not feed it — unless the deploy is a tag the release gate qualifies.
88
+ * Only a DECLARED profile is refused: an absent key reads release-heavy for ship, but a repo that never
89
+ * declared is not suddenly failing; it gets a suggestion instead. Returns null or `{ level, message }`.
90
+ */
91
+ function liveRestriction({ profile, declared, exposure, deploy }) {
92
+ if (exposure !== 'live') return null;
93
+ if (deploy === 'tag') return null;
94
+ if (profile === 'gated' || profile === 'promote') return null;
95
+ if (declared) {
96
+ return { level: 'fail', message: `${KEY}: ${profile} on exposure: live with deploy: ${deploy || '(none)'} — ${profile} allows a heavy-red trunk, and here the promotion deploys it. Choose gated, or deploy from a qualified tag (CONVENTIONS.md §7, Integration profiles)` };
97
+ }
98
+ return { level: 'suggest', message: `exposure: live reads ${KEY}: ${DEFAULT_PROFILE} by default, which allows a heavy-red trunk to be promoted — consider declaring ${KEY}: gated (CONVENTIONS.md §7, Integration profiles)` };
99
+ }
100
+
101
+ /**
102
+ * The gate a `colab ship` landing must pass under the profile, given the heavy verdict at the
103
+ * candidate. Only `gated` gates a landing; every other profile returns null (ship reads the light
104
+ * lane exactly as before). `docsOnly` landings never wait on CI (#606) and are exempt here too.
105
+ * → null | { ok, action: 'pass'|'dispatch'|'wait'|'refuse', detail }
106
+ */
107
+ function landingGate({ profile, docsOnly = false, heavyPresent, verdict, file, at }) {
108
+ if (profile !== 'gated' || docsOnly) return null;
109
+ if (!heavyPresent) {
110
+ return { ok: false, action: 'refuse', detail: `${KEY}: gated, but no .github/workflows/${file} at ${at} — gated lands only on a green heavy run, and there is no heavy lane to run (add one from templates/ci-<stack>-heavy.yml, or name it with ${HEAVY_KEY}:)` };
111
+ }
112
+ const v = verdict || { state: 'unread', why: 'not read' };
113
+ const link = v.url ? ` (${v.url})` : '';
114
+ switch (v.state) {
115
+ case 'green': return { ok: true, action: 'pass', detail: `${KEY}: gated — heavy lane green at ${at}${link}` };
116
+ case 'none': return { ok: false, action: 'dispatch', detail: `${KEY}: gated — no heavy run at ${at} yet (${v.why})` };
117
+ case 'pending': return { ok: false, action: 'wait', detail: `${KEY}: gated — ${v.why} at ${at}${link}` };
118
+ case 'red': return { ok: false, action: 'refuse', detail: `${KEY}: gated — ${v.why} at ${at}${link}; it blocks landing (fix it, or re-dispatch the heavy lane once a flake is proven)` };
119
+ default: return { ok: false, action: 'wait', detail: `${KEY}: gated — cannot read the heavy lane at ${at} (${v.why})` };
120
+ }
121
+ }
122
+
123
+ /**
124
+ * A batch's effective verdict under `gated`: the combined (light) verdict AND the heavy verdict at the
125
+ * batch head. Shapes match ship-batch.js combinedVerdict (`{state, attempt, runIds, why}`), so the
126
+ * existing re-run / split / land machinery reads it unchanged — a heavy red splits the wave toward the
127
+ * culprit exactly as a light red does. `heavy: null` (profile not gated) → the light verdict as is.
128
+ */
129
+ function waveVerdict(light, heavy) {
130
+ if (!heavy || !light) return light;
131
+ if (light.state !== 'green') return light;
132
+ if (heavy.state === 'green') return { ...light, why: `${light.why}; heavy lane green` };
133
+ if (heavy.state === 'red') return { ...light, state: 'red', why: `heavy lane: ${heavy.why}${heavy.url ? ` (${heavy.url}; re-dispatch it for a red:infra, it is not one of the run ids below)` : ''}` };
134
+ return { ...light, state: 'pending', heavyMissing: heavy.state === 'none', why: `light green; heavy lane: ${heavy.why}` };
135
+ }
136
+
137
+ /**
138
+ * The final release's heavy-lane condition — under EVERY profile (#610). A repo with no heavy lane at
139
+ * the candidate has nothing to gate (#607's templates say the same: "no heavy lane here → no gate"),
140
+ * so it passes and says so; refusing every release of a repo that never wrote one would break every
141
+ * adopter. With one: green → ok; red → blocking; none / running / unreadable → `pending` — the
142
+ * candidate keeps testing, it is not refused (the release workflow starts the heavy lane at each
143
+ * candidate; by hand: the printed command).
144
+ * → { ok, pending, detail }
145
+ */
146
+ function releaseHeavyCondition({ present, file, verdict, at, ref }) {
147
+ if (!present) return { ok: true, pending: false, detail: `no .github/workflows/${file} at ${at} — no heavy lane in this repo, nothing to gate` };
148
+ const v = verdict || { state: 'unread', why: 'not read' };
149
+ const link = v.url ? ` (${v.url})` : '';
150
+ const start = `gh workflow run ${file} --ref ${ref || '<the candidate tag>'} -f ref=${ref || '<the candidate tag>'}`;
151
+ if (v.state === 'green') return { ok: true, pending: false, detail: `heavy lane green at ${at}${link}` };
152
+ if (v.state === 'red') return { ok: false, pending: false, detail: `heavy lane red at ${at}${link} — a final needs it green at this exact sha: re-run it green, or cut a new candidate` };
153
+ if (v.state === 'pending') return { ok: false, pending: true, detail: `heavy lane still running at ${at}${link} — no final until it is green` };
154
+ if (v.state === 'none') return { ok: false, pending: true, detail: `no heavy run at ${at} yet — start it: ${start}` };
155
+ return { ok: false, pending: true, detail: `cannot read the heavy lane at ${at} (${v.why}) — not finalized in this run` };
156
+ }
157
+
158
+ module.exports = {
159
+ KEY, HEAVY_KEY, PROFILES, DEFAULT_PROFILE, DEFAULT_HEAVY_WORKFLOW,
160
+ parseProfile, parseHeavyWorkflow, heavyVerdict, liveRestriction, landingGate, waveVerdict, releaseHeavyCondition,
161
+ };
@@ -931,6 +931,8 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
931
931
  * triggers workflow-triggers.js prereleaseTagTriggers(...) findings
932
932
  * lastFinal, suggestion, override, tags, tagsAtSha
933
933
  * ci, suite, schema, switches { ok, detail } each, measured by the caller
934
+ * heavy #610 — integration-profile.js releaseHeavyCondition(), read on the final routes only;
935
+ * absent → no row
934
936
  *
935
937
  * Returns { ok, checks: [{ condition, ok, detail }], refusals, version, tag, bump, overridden }.
936
938
  * Every check is reported, not just the first failure: a caller fixing one refusal should not
@@ -1062,6 +1064,14 @@ function decide(facts) {
1062
1064
  else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
1063
1065
  }
1064
1066
 
1067
+ // #610: a final needs the heavy lane green at its exact sha, under every integration profile. Only
1068
+ // the two final routes tag a final here; a candidate is gated at `release finalize`. A heavy run
1069
+ // still to start or still running is the route holding (a no-op under --auto), not a refusal.
1070
+ if (finalRoute && tag && f.heavy) {
1071
+ add('heavy-lane', f.heavy.ok, f.heavy.detail, f.heavy.pending);
1072
+ if (!f.heavy.ok && f.heavy.pending && f.auto) noop = true;
1073
+ }
1074
+
1065
1075
  // #446: what the fast route keeps in place of the test period it does not have.
1066
1076
  let handoff = null;
1067
1077
  let grant = null;
@@ -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', 'deploy-report', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -591,6 +591,7 @@ function handoffCommand(tag) {
591
591
  * trunk trunkGreenVerdict(...)
592
592
  * regressions regressionVerdict(...)
593
593
  * ci, suite, schema, switches { ok, detail }
594
+ * heavy #610 — integration-profile.js releaseHeavyCondition(): { ok, pending, detail }; absent → no row
594
595
  * cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
595
596
  * finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
596
597
  * read when the policy carries one; absent = unresolved, never a grant)
@@ -677,6 +678,10 @@ function decide(facts) {
677
678
  add(condition, v && v.ok, v ? v.detail : 'not measured');
678
679
  }
679
680
  if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
681
+ // #610: the heavy lane green at the candidate's exact sha, under every integration profile.
682
+ // integration-profile.js releaseHeavyCondition; absent from `facts` (a caller predating it) → no row.
683
+ const hv = f.heavy || null;
684
+ if (hv) add('heavy-lane', hv.ok, hv.detail);
680
685
  for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
681
686
  add(condition, v && v.ok, v ? v.detail : 'not measured');
682
687
  }
@@ -690,12 +695,14 @@ function decide(facts) {
690
695
 
691
696
  if (held.length) return out('held');
692
697
  if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
693
- const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
698
+ const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
699
+ && !(c.condition === 'heavy-lane' && hv && hv.pending));
694
700
  if (blocking.length) return out('refused');
695
701
  if (ownClock) {
696
702
  if (!tr.ok && !tr.pending) return out('refused');
697
703
  if (!per.elapsed || tr.pending) return out('testing');
698
704
  }
705
+ if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
699
706
  if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
700
707
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
701
708
  return out('finalized', { finalTag: cand.version });