An open source design system that's fully customizable and agent ready
TypeScript
ci: an agent lane's push runs the fast checks; the heavy suites run when ready and before merge (AST-030 FR20) (#9200)
Cindy Zhang9497856d047a
diff --git a/.github/actions/heavy-caps/action.yml b/.github/actions/heavy-caps/action.ymlindex 6a789ab704..58d3e0b8f9 100644--- a/.github/actions/heavy-caps/action.yml+++ b/.github/actions/heavy-caps/action.yml@@ -32,6 +32,7 @@ runs:if (login.endsWith('[bot]')) return;// Agent lanes share one login: each branch prefix counts as an author.+ // The same list as SHARED_AGENT_LOGINS (.github/scripts/ci-pr-gate.mjs).const shared = ['cixzhang'].includes(login);const lane = ref => (shared ? ref.split('/')[0] : '');const mine = ref => lane(ref) === lane(pr.head.ref);diff --git a/.github/scripts/ci-admission.test.mjs b/.github/scripts/ci-admission.test.mjsindex 68cf212536..729bf81b24 100644--- a/.github/scripts/ci-admission.test.mjs+++ b/.github/scripts/ci-admission.test.mjs@@ -67,14 +67,20 @@ describe('where runs wait', () => {expect(room.outputs[key]).toBe(`\${{ steps.room.outputs.${key} }}`);// Every job but the Storybook build reaches admission, directly or through// the jobs it needs, never only through the build.+ // heavy-ci, the agent-push deferral decision (spec:AST-030 FR20), is one+ // slim job beside admission that the build needs.const BESIDE = 'build-storybook';- expect(needsOf(ci.jobs[BESIDE])).toEqual(['room']);+ const DEFERRAL = 'heavy-ci';+ expect(needsOf(ci.jobs[BESIDE])).toEqual(['room', DEFERRAL]);+ expect(needsOf(ci.jobs[DEFERRAL])).toEqual(['room']);const reaches = id =>needsOf(ci.jobs[id]).some(- need => need === 'admission' || (need !== BESIDE && reaches(need)),+ need =>+ need === 'admission' ||+ (need !== BESIDE && need !== DEFERRAL && reaches(need)),);for (const id of Object.keys(ci.jobs)) {- if (!['room', 'admission', 'ci-full', BESIDE].includes(id))+ if (!['room', 'admission', 'ci-full', BESIDE, DEFERRAL].includes(id))expect(reaches(id), id).toBe(true);}});@@ -237,8 +243,12 @@ describe('peaks', () => {const closure = new Set();const visit = name => {for (const need of needsOf(ci.jobs[name])) {+ // heavy-ci decides an agent push's deferral and skips for a+ // release-check (spec:AST-030 FR20).if (- ['maintenance-request', 'room', 'admission'].includes(need) ||+ ['maintenance-request', 'room', 'admission', 'heavy-ci'].includes(+ need,+ ) ||closure.has(need))continue;@@ -299,9 +309,10 @@ describe('peaks', () => {});it('gives a pull request a peak that covers every job it starts at once', () => {- // The jobs that need only the waits start together the moment admission- // ends; the Storybook build may still be running then.- const waits = ['room', 'admission'];+ // The jobs that need only the waits (and heavy-ci, the deferral decision+ // that runs only for an agent push; spec:AST-030 FR20) start together the+ // moment admission ends; the Storybook build may still be running then.+ const waits = ['room', 'admission', 'heavy-ci'];const first = Object.keys(ci.jobs).filter(name =>!waits.includes(name) &&diff --git a/.github/scripts/ci-docsite-browser.test.mjs b/.github/scripts/ci-docsite-browser.test.mjsindex 3976f35723..8f2fe75b84 100644--- a/.github/scripts/ci-docsite-browser.test.mjs+++ b/.github/scripts/ci-docsite-browser.test.mjs@@ -30,8 +30,9 @@ describe('docsite-test', () => {expect(jobs['docsite-data']).toBeUndefined();expect(jobs['docsite-browser']).toBeUndefined();// Only CI's run admission, which never skips (ci-admission.test.mjs).- // room tells it when CI is full (ci-admission.test.mjs).- expect(owner.needs).toEqual(['room', 'admission']);+ // room tells it when CI is full (ci-admission.test.mjs); heavy-ci whether+ // an agent push deferred it (spec:AST-030 FR20).+ expect(owner.needs).toEqual(['room', 'admission', 'heavy-ci']);expect(owner['continue-on-error']).toBeUndefined();// A required context keeps only the draft skip in its condition; an// outside contributor's run stops at the first step with the reason.@@ -46,7 +47,9 @@ describe('docsite-test', () => {);// After the FR17 gate and the CI-is-full stop (ci-admission.test.mjs).expect(owner.steps[1].name).toBe('Stop when CI is full');- expect(owner.steps.findIndex(s => s.id === 'scope')).toBe(3);+ // Then an agent push's deferral (spec:AST-030 FR20), then the scope.+ expect(owner.steps[2].name).toBe('Heavy CI deferred');+ expect(owner.steps.findIndex(s => s.id === 'scope')).toBe(4);const builds = owner.steps.filter(s =>/pnpm -F @astryxdesign\/docsite build/.test(s.run ?? ''),diff --git a/.github/scripts/ci-heavy-deferral.test.mjs b/.github/scripts/ci-heavy-deferral.test.mjsnew file mode 100644index 0000000000..b26f3125db--- /dev/null+++ b/.github/scripts/ci-heavy-deferral.test.mjs@@ -0,0 +1,532 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file An agent lane's push defers the heavy suites (spec:AST-030 FR20,+ * DEC-14).+ *+ * @input ci.yml, lint.yml and pr-comment.yml, evaluated as Actions would for+ * each kind of push+ * @output proofs that a deferred push runs only the fast checks, that every+ * required context it reaches fails with the reason instead of passing as+ * skipped, and that every other push, the ready and reopen events and any+ * later attempt run everything+ * @position Node contract for the `heavy-ci` decision and the jobs it gates+ */++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';++import {describe, expect, it} from 'vitest';+import yaml from 'yaml';++import {+ HEAVY_CANDIDATE,+ HEAVY_DEFERRED,+ HEAVY_DEFERRED_MESSAGE,+ HEAVY_RUNS,+ SHARED_AGENT_LOGINS,+ ungated,+} from './ci-pr-gate.mjs';++const read = name =>+ yaml.parse(+ fs.readFileSync(+ path.resolve(import.meta.dirname, '../workflows', name),+ 'utf8',+ ),+ );+const ci = read('ci.yml');+const lint = read('lint.yml');+const prComment = read('pr-comment.yml');++// The jobs that skip on a deferred push.+const HEAVY = [+ 'test-ui',+ 'test-node',+ 'native-swift-runner',+ 'test-native-swift',+ 'run-labels',+ 'test-build',+ 'build-storybook',+ 'pr-interaction',+ 'pr-interaction-webkit',+];+// The required contexts ci.yml reports (spec:AST-030 FR7).+const REQUIRED = ['test', 'build', 'docsite-test'];++function pushEvent({+ action = 'synchronize',+ attempt = '1',+ login = 'cixzhang',+ base = 'main',+ head = 'fix/thing',+} = {}) {+ return {+ event_name: 'pull_request',+ repository: 'meta/astryx',+ run_attempt: attempt,+ base_ref: base,+ head_ref: head,+ event: {+ action,+ pull_request: {+ draft: false,+ user: {login},+ head: {repo: {full_name: 'meta/astryx'}},+ labels: [],+ },+ },+ };+}++/**+ * Evaluates a job or step condition as Actions would. `needs` maps a job id+ * to `{result, outputs}`; a condition with no status-check function also+ * needs every needed job to have succeeded.+ */+function evaluate(condition, {github, needs = {}, jobNeeds = []}) {+ const expression = String(condition)+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')+ .replace(/\.labels\.\*\.name/g, '.labels.map(l => l.name)')+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');+ const hasStatus = /\b(always|cancelled|failure|success)\(\)/.test(expression);+ const needed = [jobNeeds].flat().map(id => needs[id] ?? {result: 'success'});+ const succeeded = needed.every(need => need.result === 'success');+ const all = new Proxy(needs, {+ get: (target, key) => target[key] ?? {result: 'success', outputs: {}},+ });+ return Boolean(+ Function(+ 'github',+ 'needs',+ 'inputs',+ 'always',+ 'cancelled',+ 'success',+ 'failure',+ 'startsWith',+ 'contains',+ 'fromJSON',+ `return ${hasStatus ? '' : 'success() && '}(${expression});`,+ )(+ github,+ all,+ {},+ () => true,+ () => false,+ () => succeeded,+ () => !succeeded,+ (value, prefix) => String(value ?? '').startsWith(prefix),+ (list, item) => list.includes(item),+ JSON.parse,+ ),+ );+}++/** The `heavy-ci` result and output a push leaves, by its own condition. */+function heavyCi(github, {specOnly = false} = {}) {+ if (!evaluate(ci.jobs['heavy-ci'].if, {github}))+ return {result: 'skipped', outputs: {}};+ return {+ result: 'success',+ outputs: {deferred: specOnly ? 'false' : 'true'},+ };+}++/** Whether a job starts, with every need but `heavy-ci` as given. */+function starts(id, github, {specOnly, others = 'success'} = {}) {+ const job = ci.jobs[id];+ const needs = Object.fromEntries(+ [job.needs ?? []]+ .flat()+ .map(need => [+ need,+ need === 'heavy-ci'+ ? heavyCi(github, {specOnly})+ : {result: others, outputs: {}},+ ]),+ );+ return evaluate(job.if, {github, needs, jobNeeds: job.needs ?? []});+}++const deferralStep = id =>+ ci.jobs[id].steps.find(step => step.name === 'Heavy CI deferred');++describe('which pushes defer the heavy suites (spec:AST-030 FR20)', () => {+ it('is a push to a ready agent-lane pull request into main, in its first attempt', () => {+ expect(ci.jobs['heavy-ci'].if).toContain(HEAVY_CANDIDATE);+ expect(evaluate(HEAVY_CANDIDATE, {github: pushEvent()})).toBe(true);+ });++ it.each([+ ['marked ready', {action: 'ready_for_review'}],+ ['opened', {action: 'opened'}],+ ['reopened', {action: 'reopened'}],+ ['re-run (the pre-merge run)', {attempt: '2'}],+ ['from another author', {login: 'someone'}],+ ['a release merge-back', {head: 'chore/merge-v1.2.3-to-main'}],+ ])('runs everything when the pull request is %s', (_, event) => {+ const github = pushEvent(event);+ expect(evaluate(HEAVY_CANDIDATE, {github})).toBe(false);+ expect(heavyCi(github).result).toBe('skipped');+ for (const id of HEAVY) expect(starts(id, github), id).toBe(true);+ for (const id of REQUIRED) {+ expect(starts(id, github), id).toBe(true);+ expect(+ evaluate(deferralStep(id).if, {+ github,+ needs: {'heavy-ci': heavyCi(github)},+ }),+ id,+ ).toBe(false);+ }+ });++ it('never defers a release-branch pull request', () => {+ const github = pushEvent({base: 'release/v1.2.3'});+ expect(heavyCi(github).result).toBe('skipped');+ });++ it('names the shared agent logins in one list, the heavy-suite caps included', () => {+ expect(HEAVY_CANDIDATE).toContain(+ `fromJSON('${JSON.stringify(SHARED_AGENT_LOGINS)}')`,+ );+ const caps = fs.readFileSync(+ path.resolve(import.meta.dirname, '../actions/heavy-caps/action.yml'),+ 'utf8',+ );+ const listed = /const shared = (\[[^\]]*\])\.includes\(login\)/.exec(+ caps,+ )[1];+ expect(JSON.parse(listed.replaceAll("'", '"'))).toEqual(+ SHARED_AGENT_LOGINS,+ );+ });++ it('runs everything for a spec-only change', () => {+ const github = pushEvent();+ for (const id of HEAVY)+ expect(starts(id, github, {specOnly: true}), id).toBe(true);+ });+});++describe('a deferred push', () => {+ const github = pushEvent();++ it('skips every heavy job', () => {+ for (const id of HEAVY) {+ expect(starts(id, github), id).toBe(false);+ // The deferral sits right after the gate, and ungated() sees past it.+ expect(String(ci.jobs[id].if), id).toContain(`&& (${HEAVY_RUNS} && (`);+ expect(ungated(ci.jobs[id].if), id).not.toContain('heavy-ci');+ }+ });++ it('still runs the fast checks: typecheck and lint', () => {+ expect(starts('typecheck', github)).toBe(true);+ expect(JSON.stringify(ci.jobs.typecheck)).not.toContain('heavy-ci');+ expect(JSON.stringify(lint)).not.toContain('heavy-ci');+ });++ it('fails every required context with the reason, never passing as skipped', () => {+ for (const id of REQUIRED) {+ // The job starts even though the jobs it joins skipped...+ expect(starts(id, github, {others: 'skipped'}), id).toBe(true);+ // ...and its deferral step, which exits 1, runs right after the fork+ // gate and the CI-is-full stop (and, in `test`, the PR report's+ // record), so the context fails before any join could pass.+ const steps = ci.jobs[id].steps;+ const step = deferralStep(id);+ const before = steps.slice(0, steps.indexOf(step)).map(item => item.name);+ expect(before.slice(0, 2), id).toEqual([+ 'Require a branch in this repository or the ci:run label',+ 'Stop when CI is full',+ ]);+ expect(before.slice(2), id).toEqual(+ id === 'test'+ ? [+ 'Record the deferral for the PR report',+ 'Upload the deferral for the PR report',+ ]+ : [],+ );+ expect(step.if).toBe(HEAVY_DEFERRED);+ expect(+ evaluate(step.if, {github, needs: {'heavy-ci': heavyCi(github)}}),+ id,+ ).toBe(true);+ expect(step.run, id).toContain(`::error::${HEAVY_DEFERRED_MESSAGE}`);+ expect(step.run, id).toMatch(/\bexit 1\s*$/);+ }+ });++ it('decides with one cheap job that reads the trusted scope', () => {+ const job = ci.jobs['heavy-ci'];+ expect(job['runs-on']).toBe('ubuntu-slim');+ expect(job.outputs.deferred).toBe('${{ steps.decide.outputs.deferred }}');+ expect(+ job.steps.some(step => step.uses?.endsWith('/actions/test-scope')),+ ).toBe(true);+ for (const id of [...HEAVY, ...REQUIRED])+ expect([ci.jobs[id].needs].flat(), id).toContain('heavy-ci');+ });++ it.each([+ ['true', 'false', ''],+ ['false', 'true', HEAVY_DEFERRED_MESSAGE],+ ['', 'true', HEAVY_DEFERRED_MESSAGE],+ ])(+ 'defers unless the change is spec-only (spec_only=%s → deferred=%s)',+ (specOnly, deferred, summary) => {+ const step = ci.jobs['heavy-ci'].steps.find(item => item.id === 'decide');+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'heavy-ci-'));+ try {+ const output = path.join(dir, 'output');+ const stepSummary = path.join(dir, 'summary');+ const result = spawnSync(+ 'bash',+ ['-e', '-c', step.run.replaceAll(/\$\{\{[^}]*\}\}/g, 'abc')],+ {+ cwd: dir,+ encoding: 'utf8',+ env: {+ ...process.env,+ SPEC_ONLY: specOnly,+ GITHUB_OUTPUT: output,+ GITHUB_STEP_SUMMARY: stepSummary,+ GITHUB_RUN_ID: '7',+ GITHUB_RUN_ATTEMPT: '1',+ },+ },+ );+ expect(result.status, result.stderr).toBe(0);+ expect(fs.readFileSync(output, 'utf8')).toBe(`deferred=${deferred}\n`);+ expect(+ fs.existsSync(stepSummary)+ ? fs.readFileSync(stepSummary, 'utf8')+ : '',+ ).toBe(summary ? `${summary}.\n` : '');+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ },+ );+});++describe("heavy-ci's skip on every other run", () => {+ // Actions' implicit success() needs every ancestor, not only the direct+ // needs, to have succeeded; heavy-ci skips on every run but an agent push,+ // so any job below it without its own status check would skip too.+ const needsOf = id => [ci.jobs[id].needs ?? []].flat();+ const ancestors = (id, seen = new Set()) => {+ for (const need of needsOf(id))+ if (!seen.has(need)) {+ seen.add(need);+ ancestors(need, seen);+ }+ return seen;+ };+ const below = Object.keys(ci.jobs).filter(id =>+ ancestors(id).has('heavy-ci'),+ );++ it('gives every job below it a status check', () => {+ expect(below.length).toBeGreaterThan(HEAVY.length);+ for (const id of below)+ expect(String(ci.jobs[id].if), id).toMatch(+ /\b(always|cancelled|success|failure)\(\)/,+ );+ });++ /** Every job's start as Actions decides it, ancestors included. */+ function plan(github, inputs = {}, {full = false} = {}) {+ const results = {};+ const order = [];+ const visit = id => {+ if (order.includes(id)) return;+ for (const need of needsOf(id)) visit(need);+ order.push(id);+ };+ Object.keys(ci.jobs).forEach(visit);+ for (const id of order) {+ const job = ci.jobs[id];+ const needs = Object.fromEntries(+ needsOf(id).map(need => [need, results[need]]),+ );+ const all = [...ancestors(id)].map(need => results[need]);+ const condition = String(job.if ?? 'true')+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')+ .replace(/\.labels\.\*\.name/g, '.labels.map(l => l.name)')+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');+ const hasStatus = /\b(always|cancelled|failure|success)\(\)/.test(+ condition,+ );+ const ok = all.every(item => item.result === 'success');+ const runs =+ (hasStatus || ok) &&+ Boolean(+ Function(+ 'github',+ 'needs',+ 'inputs',+ 'always',+ 'cancelled',+ 'success',+ 'failure',+ 'startsWith',+ 'contains',+ 'fromJSON',+ `return (${condition});`,+ )(+ github,+ needs,+ inputs,+ () => true,+ () => false,+ () => ok,+ () => !ok,+ (value, prefix) => String(value ?? '').startsWith(prefix),+ (list, item) => list.includes(item),+ JSON.parse,+ ),+ );+ results[id] = {+ // When CI is full, admission fails at its first step.+ result: !runs+ ? 'skipped'+ : id === 'admission' && full+ ? 'failure'+ : 'success',+ outputs:+ id === 'run-labels'+ ? {a11y: 'true', rtl: 'true', visual: 'true'}+ : id === 'room'+ ? {full: String(full)}+ : {},+ };+ }+ return results;+ }++ it("runs a release-check's every browser owner", () => {+ const results = plan(+ {event_name: 'workflow_dispatch', repository: 'meta/astryx', event: {}},+ {operation: 'release-check', 'release-branch': 'main'},+ );+ expect(results['heavy-ci'].result).toBe('skipped');+ for (const id of [+ 'build-storybook',+ 'pr-a11y-shard',+ 'a11y-contracts-shard',+ 'pr-a11y-guards',+ 'pr-a11y-specs',+ 'pr-rtl-shard',+ 'pr-a11y-audit',+ 'release-check',+ ])+ expect(results[id].result, id).toBe('success');+ });++ it('starts no heavy job when CI is full (spec:AST-030 FR16)', () => {+ // A fork's run with ci:run cannot cancel itself, so only the jobs' own+ // conditions stop it.+ const github = pushEvent({login: 'someone'});+ github.event.pull_request.head.repo.full_name = 'someone/astryx';+ github.event.pull_request.labels = [{name: 'ci:run'}];+ const results = plan(github, {}, {full: true});+ expect(results.admission.result).toBe('failure');+ expect(results['heavy-ci'].result).toBe('skipped');+ // test-native-swift always runs to report its runner, as on main.+ for (const id of HEAVY.filter(item => item !== 'test-native-swift'))+ expect(results[id].result, id).toBe('skipped');+ });++ it('runs the suites an opt-in label asks for on a pull request', () => {+ const github = pushEvent({login: 'someone', action: 'labeled'});+ github.event.pull_request.labels = [+ {name: 'ci:run-a11y'},+ {name: 'ci:run-rtl'},+ ];+ const results = plan(github);+ expect(results['heavy-ci'].result).toBe('skipped');+ for (const id of ['pr-a11y-guards', 'pr-a11y-specs', 'pr-rtl-shard'])+ expect(results[id].result, id).toBe('success');+ });+});++describe('the PR report on a deferred push', () => {+ const comment = prComment.jobs.comment;++ it("reads the run attempt's deferral, only for a failed run", () => {+ const download = comment.steps.find(+ step => step.id === 'deferral-download',+ );+ expect(download.uses).toBe('actions/download-artifact@v8');+ expect(download.with.name).toBe(+ 'heavy-ci-deferred-${{ steps.identity.outputs.run_attempt }}',+ );+ expect(download.with['run-id']).toBe(+ '${{ steps.identity.outputs.run_id }}',+ );+ expect(download.if).toContain(+ "steps.identity.outputs.source_conclusion == 'failure'",+ );+ expect(download['continue-on-error']).toBe(true);+ // `test` records it: a failed-jobs re-run repeats `test` (it failed) and+ // keeps heavy-ci's output, so that attempt has its own record; a full+ // re-run is a later attempt, which never defers.+ const steps = ci.jobs.test.steps;+ const record = steps.find(+ step => step.name === 'Record the deferral for the PR report',+ );+ const upload = steps.find(step =>+ step.uses?.startsWith('actions/upload-artifact'),+ );+ expect(record.if).toBe(HEAVY_DEFERRED);+ expect(upload.if).toBe(HEAVY_DEFERRED);+ expect(upload.with.name).toBe(+ 'heavy-ci-deferred-${{ github.run_attempt }}',+ );+ expect(+ ci.jobs['heavy-ci'].steps.some(step =>+ step.uses?.startsWith('actions/upload-artifact'),+ ),+ ).toBe(false);+ });++ it('writes the record the report reads', () => {+ const record = ci.jobs.test.steps.find(+ step => step.name === 'Record the deferral for the PR report',+ );+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'heavy-ci-'));+ try {+ const result = spawnSync(+ 'bash',+ ['-e', '-c', record.run.replaceAll(/\$\{\{[^}]*\}\}/g, 'abc')],+ {+ cwd: dir,+ encoding: 'utf8',+ env: {...process.env, GITHUB_RUN_ID: '7', GITHUB_RUN_ATTEMPT: '2'},+ },+ );+ expect(result.status, result.stderr).toBe(0);+ expect(+ JSON.parse(+ fs.readFileSync(path.join(dir, 'heavy-ci-deferred.json'), 'utf8'),+ ),+ ).toEqual({headSha: 'abc', runId: '7', runAttempt: '2'});+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ }+ });++ it('says the heavy CI was deferred', () => {+ const publish = comment.steps.find(step => step.id === 'publish');+ expect(publish.with.script).toContain(HEAVY_DEFERRED_MESSAGE);+ expect(publish.with.script).toContain(+ 'heavy-ci-deferred/heavy-ci-deferred.json',+ );+ });+});diff --git a/.github/scripts/ci-interaction-webkit.test.mjs b/.github/scripts/ci-interaction-webkit.test.mjsindex 707e94dc10..f99f839b58 100644--- a/.github/scripts/ci-interaction-webkit.test.mjs+++ b/.github/scripts/ci-interaction-webkit.test.mjs@@ -59,7 +59,12 @@ describe('WebKit interaction proof routing', () => {"github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true'",);// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).- expect(webkit.needs).toEqual(['room', 'admission', 'build-storybook']);+ expect(webkit.needs).toEqual([+ 'room',+ 'admission',+ 'heavy-ci',+ 'build-storybook',+ ]);});it('stays on a standard runner within the 15-minute budget', () => {diff --git a/.github/scripts/ci-interaction.test.mjs b/.github/scripts/ci-interaction.test.mjsindex cf7a52b76d..296967dd64 100644--- a/.github/scripts/ci-interaction.test.mjs+++ b/.github/scripts/ci-interaction.test.mjs@@ -50,7 +50,12 @@ describe('interaction proof routing', () => {"github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true'",);// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).- expect(proofs.needs).toEqual(['room', 'admission', 'build-storybook']);+ expect(proofs.needs).toEqual([+ 'room',+ 'admission',+ 'heavy-ci',+ 'build-storybook',+ ]);});it('decides its own scope first, and gates every later step on it', () => {diff --git a/.github/scripts/ci-native-swift.test.mjs b/.github/scripts/ci-native-swift.test.mjsindex 944ff89dba..5fc0486465 100644--- a/.github/scripts/ci-native-swift.test.mjs+++ b/.github/scripts/ci-native-swift.test.mjs@@ -59,7 +59,7 @@ describe('native Swift routing', () => {expect(runner.steps.find(s => s.id === 'scope').uses).toBe('./.test-scope/.github/actions/test-scope',);- expect(swift.needs).toEqual(['native-swift-runner']);+ expect(swift.needs).toEqual(['heavy-ci', 'native-swift-runner']);expect(swift['runs-on']).toBe(`\${{ ${applies} && 'macos-15' || 'ubuntu-slim' }}`,);diff --git a/.github/scripts/ci-pr-gate.mjs b/.github/scripts/ci-pr-gate.mjsindex 3b8901f842..14725f9ba0 100644--- a/.github/scripts/ci-pr-gate.mjs+++ b/.github/scripts/ci-pr-gate.mjs@@ -33,13 +33,62 @@ export function gated(condition, gate = PR_CI_GATE) {return condition.startsWith('${{') ? `\${{ ${wrapped} }}` : wrapped;}-/** The job's own condition, without the gate in front. */+/**+ * The job's own condition, without the gate in front, nor the heavy-suite+ * deferral a heavy job adds after it (spec:AST-030 FR20).+ */export function ungated(condition) {- const expression = condition.replace(/^\$\{\{\s*|\s*\}\}$/g, '');+ let expression = condition.replace(/^\$\{\{\s*|\s*\}\}$/g, '');for (const gate of [PR_CI_GATE, PR_REPORT_GATE]) {const prefix = `${gate} && (`;- if (expression.startsWith(prefix))- return expression.slice(prefix.length, -1);+ if (expression.startsWith(prefix)) {+ expression = expression.slice(prefix.length, -1);+ break;+ }}+ if (expression.startsWith(`${HEAVY_RUNS} && (`))+ expression = expression.slice(HEAVY_RUNS.length + 5, -1);+ if (expression.startsWith(`${HEAVY_ADMITTED} && (`))+ expression = expression.slice(HEAVY_ADMITTED.length + 5, -1);return expression;}++/**+ * A push that defers the heavy suites (spec:AST-030 FR20, DEC-14): a push to a+ * ready pull request from the shared agent login, in its first attempt, into+ * `main`. A release merge-back is never deferred. The `heavy-ci` job runs only+ * then, and defers unless the change is spec-only.+ */+/**+ * The shared agent logins. The heavy-suite caps+ * (.github/actions/heavy-caps) list the same logins, and a test holds the two+ * lists equal.+ */+export const SHARED_AGENT_LOGINS = ['cixzhang'];++export const HEAVY_CANDIDATE =+ "(github.event_name == 'pull_request' && github.event.action == 'synchronize' && " ++ `github.run_attempt == '1' && contains(fromJSON('${JSON.stringify(SHARED_AGENT_LOGINS)}'), github.event.pull_request.user.login) && ` ++ "github.base_ref == 'main' && !startsWith(github.head_ref, 'chore/merge-v'))";++/** `heavy-ci` decided to defer this push's heavy suites. */+export const HEAVY_DEFERRED = "needs.heavy-ci.outputs.deferred == 'true'";++/**+ * A heavy job's condition after the gate. `heavy-ci` skips for every push it+ * does not decide, so the job runs then too (`!cancelled()`, not success()).+ */+export const HEAVY_RUNS =+ "!cancelled() && needs.heavy-ci.outputs.deferred != 'true'";++/**+ * `!cancelled()` above also drops Actions' implicit success check, so a heavy+ * job that needs admission and had no status check of its own checks+ * admission itself: when CI is full admission fails, and the job must stop+ * (spec:AST-030 FR16).+ */+export const HEAVY_ADMITTED = "needs.admission.result == 'success'";++/** What a deferred required check and the PR report say. */+export const HEAVY_DEFERRED_MESSAGE =+ 'Heavy CI deferred: runs when marked ready and before merge';diff --git a/.github/scripts/ci-pr-gate.test.mjs b/.github/scripts/ci-pr-gate.test.mjsindex 794c5c70d4..becaebab8a 100644--- a/.github/scripts/ci-pr-gate.test.mjs+++ b/.github/scripts/ci-pr-gate.test.mjs@@ -195,6 +195,21 @@ describe('pull-request CI gate (spec:AST-030 FR17)', () => {!/always\(\)|cancelled\(\)|failure\(\)/.test(condition))continue;+ // A job that runs only once a gated job it needs succeeded is gated+ // through it (its status check keeps an ancestor's skip, such as+ // heavy-ci's, from skipping it; spec:AST-030 FR20).+ if (+ [job.needs ?? []]+ .flat()+ .some(+ need =>+ condition.includes(`needs.${need}.result == 'success'`) &&+ startsWithGate(PR_CI_GATE).test(+ String(value.jobs[need]?.if ?? ''),+ ),+ )+ )+ continue;if (/^(\$\{\{\s*)?(always\(\) && )?github\.event_name == 'workflow_dispatch' &&/.test(condition,diff --git a/.github/scripts/ci-test-routing.test.mjs b/.github/scripts/ci-test-routing.test.mjsindex 0eb8d3e1c7..9a3e13e2b2 100644--- a/.github/scripts/ci-test-routing.test.mjs+++ b/.github/scripts/ci-test-routing.test.mjs@@ -786,7 +786,12 @@ describe('ci.yml interaction proofs', () => {// One fixed runner: out of scope, every step after the scope step skips.expect(KNOWN_RUNNERS.has(job['runs-on']), job['runs-on']).toBe(true);// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).- expect(job.needs).toEqual(['room', 'admission', 'build-storybook']);+ expect(job.needs).toEqual([+ 'room',+ 'admission',+ 'heavy-ci',+ 'build-storybook',+ ]);const checkout = job.steps.find(candidate =>candidate.uses?.startsWith('actions/checkout@') &&diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjsindex db33e2c47e..d61280333b 100644--- a/.github/scripts/ci-tooling-routing.test.mjs+++ b/.github/scripts/ci-tooling-routing.test.mjs@@ -193,6 +193,7 @@ describe('Node-tooling CI routing', () => {// room only tells test when CI is full (ci-admission.test.mjs).expect(ci.jobs.test.needs).toEqual(['room',+ 'heavy-ci','release-bump','test-ui','test-node',@@ -203,6 +204,7 @@ describe('Node-tooling CI routing', () => {]);expect(ci.jobs.build.needs).toEqual(['room',+ 'heavy-ci','build-storybook','typecheck',]);diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 78a04e22f5..b89a74e261 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -490,8 +490,53 @@ jobs:# code and theme, nothing sent to a document the code navigated to), and# only the production build has the opaque-origin sandbox at all. The# spec-only lane validates spec records here, where it always has.+ # Whether this push defers the heavy suites (spec:AST-030 FR20, DEC-14): a+ # push to a ready agent-lane pull request (the shared agent login), in its+ # first attempt, runs only the fast checks (lint, typecheck). The heavy jobs+ # skip, and the required checks fail with the reason until the pull request+ # is marked ready or reopened, or its run is re-run in full before merge+ # (any later attempt runs everything). A spec-only change is never deferred.+ # Every other run skips this job at once, so it delays nothing; every job+ # below it carries a status check, so the skip never skips them. It needs+ # only room, beside admission, so the Storybook build it gates still starts+ # with room (spec:AST-030 FR16), and like room it holds one slim job.+ heavy-ci:+ needs: [room]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name == 'pull_request' && github.event.action == 'synchronize' && github.run_attempt == '1' && contains(fromJSON('["cixzhang"]'), github.event.pull_request.user.login) && github.base_ref == 'main' && !startsWith(github.head_ref, 'chore/merge-v')) && needs.room.outputs.full != 'true') }}+ runs-on: ubuntu-slim+ timeout-minutes: 5+ permissions:+ contents: read+ pull-requests: read+ outputs:+ deferred: ${{ steps.decide.outputs.deferred }}+ steps:+ - name: Check out the scope action+ uses: actions/checkout@v7+ with:+ sparse-checkout: .github/actions/test-scope+ path: .test-scope+ persist-credentials: false++ - name: Decide this push's scope+ id: scope+ uses: ./.test-scope/.github/actions/test-scope++ - name: Defer the heavy suites unless the change is spec-only+ id: decide+ env:+ SPEC_ONLY: ${{ steps.scope.outputs.spec_only }}+ run: |+ if [ "$SPEC_ONLY" = true ]; then+ echo 'deferred=false' >> "$GITHUB_OUTPUT"+ exit 0+ fi+ echo 'deferred=true' >> "$GITHUB_OUTPUT"+ echo "::notice title=Heavy CI deferred::Heavy CI deferred: runs when marked ready and before merge. Mark the pull request ready, reopen it, or re-run all jobs of this run to run everything."+ echo "Heavy CI deferred: runs when marked ready and before merge." >> "$GITHUB_STEP_SUMMARY"+docsite-test:- needs: [room, admission]+ needs: [room, admission, heavy-ci]if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled()) }}# The Next.js production build uses every core it gets.runs-on: ubuntu-latest@@ -514,6 +559,14 @@ jobs:echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."exit 1+ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the+ # required check fails with the reason, never passes as skipped.+ - name: Heavy CI deferred+ if: needs.heavy-ci.outputs.deferred == 'true'+ run: |+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."+ exit 1+- name: Check out the scope actionuses: actions/checkout@v7with:@@ -632,8 +685,8 @@ jobs:# build-storybook + typecheck below.test-ui:name: test-ui (${{ matrix.shard }}/${{ strategy.job-total }})- needs: [admission]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}+ needs: [admission, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}# One runner ran the whole UI project in ~16 minutes and set the PR's wall# time. Vitest's --shard gives each leg an equal share of the files; the# two slowest files (~3.5 minutes each) bound a leg, so more legs stop@@ -747,8 +800,8 @@ jobs:test-node:name: test-node (${{ matrix.shard }}/${{ strategy.job-total }})- needs: [admission]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}+ needs: [admission, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}# One runner ran the Node project in ~12 minutes. Vitest's --shard splits# the files across the legs; `test` joins them.strategy:@@ -841,8 +894,8 @@ jobs:# test-native-swift runs on macOS only then. It reads the same scope step as# every test job; anything undecidable picks macOS.native-swift-runner:- needs: [admission]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}+ needs: [admission, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}runs-on: ubuntu-slimtimeout-minutes: 5permissions:@@ -865,8 +918,8 @@ jobs:paths: '^packages/native/.*(\.swift|/Package\.swift)$|^\.github/scripts/native-swift\.sh$|^\.github/actions/test-scope/'test-native-swift:- needs: [native-swift-runner]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled()) }}+ needs: [heavy-ci, native-swift-runner]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled())) }}runs-on: ${{ needs.native-swift-runner.outputs.applies == 'true' && 'macos-15' || 'ubuntu-slim' }}timeout-minutes: 30permissions:@@ -962,6 +1015,7 @@ jobs:needs:[room,+ heavy-ci,release-bump,test-ui,test-node,@@ -990,6 +1044,30 @@ jobs:echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."exit 1+ # The PR report says why the heavy checks did not run. Recorded here,+ # in a job a failed-jobs re-run repeats, so its attempt has the record.+ - name: Record the deferral for the PR report+ if: needs.heavy-ci.outputs.deferred == 'true'+ run: |+ printf '{"headSha":"%s","runId":"%s","runAttempt":"%s"}\n' \+ "${{ github.event.pull_request.head.sha }}" "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" > heavy-ci-deferred.json++ - name: Upload the deferral for the PR report+ if: needs.heavy-ci.outputs.deferred == 'true'+ uses: actions/upload-artifact@v7+ with:+ name: heavy-ci-deferred-${{ github.run_attempt }}+ path: heavy-ci-deferred.json+ retention-days: 7++ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the+ # required check fails with the reason, never passes as skipped.+ - name: Heavy CI deferred+ if: needs.heavy-ci.outputs.deferred == 'true'+ run: |+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."+ exit 1+- name: Check out the scope actionuses: actions/checkout@v7with:@@ -1035,8 +1113,8 @@ jobs:# own terms. The decision script comes from the merge commit's trusted# sparse checkout, and a lookup that fails denies the suite.run-labels:- needs: [admission]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') }}+ needs: [admission, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check'))) }}runs-on: ubuntu-slimtimeout-minutes: 5permissions:@@ -1072,8 +1150,8 @@ jobs:# Starts once there is room for it, beside admission's wait for the rest of# the run; every job that uses its build also needs admission, so the heavy# legs still wait for room (spec:AST-030 FR16, DEC-16).- needs: [room]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.room.outputs.full != 'true') }}+ needs: [room, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.room.outputs.full != 'true')) }}# Every browser lane waits for this job, and the package builds and the# Storybook build run side by side (build-packages-and-storybook.mjs).runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}@@ -1553,8 +1631,8 @@ jobs:# gate passes. A skipped build-storybook job (a draft) skips this gate too;# a fork pull request without `ci:run` still reports here.build:- needs: [room, build-storybook, typecheck]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !cancelled() && (needs.build-storybook.result != 'skipped' || needs.room.outputs.full == 'true' || github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))) }}+ needs: [room, heavy-ci, build-storybook, typecheck]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !cancelled() && (needs.build-storybook.result != 'skipped' || needs.room.outputs.full == 'true' || needs.heavy-ci.outputs.deferred == 'true' || github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))) }}runs-on: ubuntu-slimpermissions: {}steps:@@ -1569,6 +1647,14 @@ jobs:echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."exit 1+ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the+ # required check fails with the reason, never passes as skipped.+ - name: Heavy CI deferred+ if: needs.heavy-ci.outputs.deferred == 'true'+ run: |+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."+ exit 1+- name: Assert parallel builds succeededrun: |echo "build-storybook: ${{ needs.build-storybook.result }}"@@ -1590,7 +1676,9 @@ jobs:pr-a11y-shard:name: pr-a11y (${{ matrix.shard }}/${{ strategy.job-total }})needs: [admission, build-storybook]- if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'+ # A status check: heavy-ci, which skips on every run but an agent push,+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.+ if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'strategy:fail-fast: falsematrix:@@ -1697,7 +1785,9 @@ jobs:pr-a11y-guards:name: pr-a11y (audit and guards)needs: [build-storybook, run-labels]- if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))+ # A status check: heavy-ci, which skips on every run but an agent push,+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.+ if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1828,7 +1918,9 @@ jobs:pr-a11y-specs:name: pr-a11y (browser specs)needs: [build-storybook, run-labels]- if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))+ # A status check: heavy-ci, which skips on every run but an agent push,+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.+ if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}permissions:@@ -1941,7 +2033,9 @@ jobs:a11y-contracts-shard:name: Accessibility spec-test contracts (${{ matrix.shard }}/${{ strategy.job-total }})needs: [admission, build-storybook]- if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'+ # A status check: heavy-ci, which skips on every run but an agent push,+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.+ if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'# Six legs: at three, the slowest leg took ~20 minutes, held by its longest# spec file; files longer than a leg's share are now cut across legs# (spec:AST-030 FR23).@@ -2051,8 +2145,8 @@ jobs:delete-merged: truepr-interaction:- needs: [room, admission, build-storybook]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true') }}+ needs: [room, admission, heavy-ci, build-storybook]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true')) }}# Frame evidence measures timing: four cores, one Playwright worker.runs-on: ubuntu-latesttimeout-minutes: 15@@ -2169,8 +2263,8 @@ jobs:# required context. Specs that need Chromium-only evidence skip themselves# in WebKit.pr-interaction-webkit:- needs: [room, admission, build-storybook]- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true') }}+ needs: [room, admission, heavy-ci, build-storybook]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true')) }}# Frame evidence measures timing: four cores, one Playwright worker.runs-on: ubuntu-latesttimeout-minutes: 15@@ -2304,8 +2398,8 @@ jobs:# package ownership explicit; the historical `test` join above projects its# result. Until runtime:build has a specialized route, broad CI dispatches it.test-build:- needs: [admission]- if: (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch')+ needs: [admission, heavy-ci]+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}runs-on: ubuntu-24.04-armtimeout-minutes: 15permissions:@@ -2866,9 +2960,12 @@ jobs:pr-rtl-shard:name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})needs: [build-storybook, run-labels]+ # A status check: heavy-ci, which skips on every run but an agent push,+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.if: >-((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||- (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))+ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&+ !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'# Core is the largest package, so its audit is split (`--shard`) and joined# by pr-rtl-merge: three ways on a pull request, six on a release-check,# where three legs took ~10 minutes (spec:AST-030 FR23). Every otherdiff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.ymlindex 3eed1a9a35..7ef340d2ee 100644--- a/.github/workflows/pr-comment.yml+++ b/.github/workflows/pr-comment.yml@@ -435,6 +435,19 @@ jobs:github-token: ${{ secrets.GITHUB_TOKEN }}continue-on-error: true+ # A failed run may be a deferred agent-lane push (spec:AST-030 FR20),+ # whose report says so instead of an unavailable analysis.+ - name: Download the heavy-CI deferral from the CI run+ id: deferral-download+ if: steps.identity.outputs.valid == 'true' && steps.identity.outputs.source_conclusion == 'failure'+ uses: actions/download-artifact@v8+ with:+ name: heavy-ci-deferred-${{ steps.identity.outputs.run_attempt }}+ path: heavy-ci-deferred+ run-id: ${{ steps.identity.outputs.run_id }}+ github-token: ${{ secrets.GITHUB_TOKEN }}+ continue-on-error: true+- name: Cross-check artifact identityid: cross-checkcontinue-on-error: true@@ -554,6 +567,9 @@ jobs:sourceRunAttempt: Number(process.env.RUN_ATTEMPT),sourceConclusion: process.env.SOURCE_CONCLUSION,},+ fallbackMessage: require('node:fs').existsSync('heavy-ci-deferred/heavy-ci-deferred.json')+ ? 'Heavy CI deferred: runs when marked ready and before merge. Lint, typecheck and any path-filtered checks ran on this push.'+ : undefined,visualFrames: {imageBase: process.env.VISUAL_IMAGE_BASE,published: process.env.VISUAL_PUBLISHED,diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex f46c1cbe18..5cfd465f62 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -964,6 +964,12 @@ Storybook story for anything you added or altered.request past either limit shows a failing check that says why, and runs infull at its pre-merge re-run. Engineering owners listed in `.github/ENGOWNERS`are not limited.+- **Pull requests from the shared agent login run the heavy suites when ready+ and before merge.** A push to a ready agent pull request runs lint and, in+ the CI workflow, only typecheck (path-filtered workflows run as usual);+ `test`, `build` and `docsite-test` fail with "Heavy CI deferred" (unless the+ change is spec-only, which runs everything) until the pull request is marked ready or reopened, or its latest run is+ re-run with **Re-run all jobs**, which runs everything at that head.## Code Stylediff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.mdindex 8fa3abb221..c47399ac7e 100644--- a/docs/specs/AST-030/spec.md+++ b/docs/specs/AST-030/spec.md@@ -403,6 +403,20 @@ they are separately named.minutes added to time to green. A flag asks the reviewer to weigh the cost;it fails no check.+- **FR20 — An agent lane's push runs the fast checks; the heavy suites run when+ it is ready and before merge.** A push to a ready pull request authored by the+ shared agent login, into `main`, in its run's first attempt, runs only+ typecheck in the CI workflow (lint keeps its own workflow), unless its trusted+ classification is spec-only; the path-filtered workflows (FR14) are+ unaffected. Its heavy jobs skip, and the required contexts `test`, `build` and `docsite-test` (FR7)+ report failure with "Heavy CI deferred: runs when marked ready and before+ merge", never success, so nothing merges on that run; the PR report says the+ same. Marking the pull request ready, opening or reopening it, and any later+ attempt of its run (the pre-merge re-run of all jobs) run every suite at that+ head. A release merge-back, a release-branch pull request, every other+ author, the review and spec gates (FR15) and the heavy-suite caps (FR16) are+ unaffected (DEC-14).+- **FR21 — Main's full unit run is about hourly and always finishes.** TheMain workflow runs its unit suites (every Vitest project of every package,never scoped to a change) only in a dispatched run, such as the one main's@@ -518,6 +532,7 @@ The nightly perf lane is the one scheduled measurement outside them (FR18).| FR17 | `ci-pr-gate.test.mjs` over every `pull_request` workflow and the shared conditions | branch here, fork with and without `ci:run`, another label, draft with the label, ready, push, merge group, dispatch | a job that can start on a pull request without the condition, a label trigger, a required job that skips for a pull request that may not run CI, or a draft or unlabelled fork that runs fails || FR18 | `perf-nightly-workflow.test.mjs`, `perf-trend.test.mjs` and `run-labels.test.mjs` | nightly and dispatch; labelled, unlabelled, draft and unvouched-fork pull requests; write, read and no access; newest label event; failed lookup; 10% boundary; metric floors; seven-day window edges; fewer than three runs; a metric over once, twice in a row, or a different metric before; recorded and pull request runs | a run on an unlabelled pull request, a label honoured from read access, a regression called at exactly 10%, under its floor or on one run alone, a run outside the window in the baseline, a pull request run that records, or a second regression issue fails || FR19 | `ci-impact.test.mjs`, `pr-preview.test.mjs` and the maintenance template | CI change and non-CI change; standard, non-standard and expression runners; added, removed and changed jobs; trigger change | a CI change reports no impact, a move onto a non-standard runner or a pool or time-to-green rise past its threshold goes unflagged, or the section names a price |+| FR20 | `ci-heavy-deferral.test.mjs` over ci.yml, lint.yml and pr-comment.yml | agent push; marked ready; opened; reopened; re-run; another author; release branch; merge-back; spec-only change; a release-check and an opt-in label run, where the decision skips; a failed-jobs re-run of a deferred push | a heavy job runs on a deferred push, a required context passes or skips on one, a ready, reopened or re-run pull request defers, a spec-only change defers, the report hides the deferral, or a job below the decision skips because it skipped || FR21 | `ci-heavy-lanes.test.mjs` dispatch cases, `main-unit-run.test.mjs` over deploy.yml, `release-check-receipt.test.mjs` | push run; dispatched unit run; tip with the scheduler's or a person's release-check, or a person's maintenance capture; unit run cancelled, skipped or timed out; newer recheck or person's run of the tip; a person's validation of an older commit; cut commit with and without a passing unit run | a push runs the unit suites, a push cancels a unit run, a release-check comes without a unit run of its commit, an incomplete run goes unreported or waits a window, or a cut publishes without a passing unit run || FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver; `vitest-shard-sequencer.test.mjs` over the recorded Node times | six UI and six Node legs; dispatch without a commit, with a commit in main's history, with a commit outside it and with a malformed one; a re-check from the workflow token and from a person, and one that names `sha`; a `sha` before the size records, and one of only spaces; four and six Node legs over the recorded suite, a file with no recorded time, a project other than `node` | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a person's `sha` run that cancels or replaces a validation of main, a `sha` lane that checks out another commit, or a `sha` run named for main's tip, or two of the slowest Node files in one leg, a file run by no leg or by two, or a split that depends on collection order fails || FR23 | `release-check-shape.test.mjs`, `a11y-contract-shard.test.mjs` and the release-check workflow contract | release-check and pull-request legs; a contract file longer than a leg's share, one it cannot name exactly, and a serial one; the recorded suite; a re-check from an admin, a maintainer and a writer, from another branch, with a short SHA and with an older commit; failed-only beside a passed, a running and a missing run | a narrower release-check, a held or over-budget leg, a test selected by no leg or by two, a re-check that a writer can start, that waits for main's running check, or that re-runs jobs of another commit fails |@@ -753,6 +768,24 @@ quiet, so the check would starve); holding a runner to wait out each push (itis billed while it waits); a daily check (main's result would lag a wholeday).+### DEC-14 — Agent lanes run the heavy suites when ready and before merge++**Reference:** `spec:AST-030/DEC-14`+**Decider:** `cixzhang`++Most pull-request runs come from the shared agent login, and an agent pushes+many times while it works; each push ran every heavy suite on a head that was+replaced minutes later. The heavy suites now run at the two heads that decide+a merge: the one that becomes ready and the one re-run before merge. Between+them lint and typecheck give fast feedback. A deferred required context fails+with its reason rather than passing as skipped, because a skipped required+check counts as passing (FR17's rule), so a deferred head cannot merge.++Rejected: leaving the required contexts pending (a commit status beside the+job's check run of the same name is ambiguous to branch protection); deferring+spec-only changes (their heavy jobs already do nothing, and every push would+then need a re-run to merge).+### DEC-15 — Main's unit suites run about hourly, in full, to completion**Reference:** `spec:AST-030/DEC-15`