Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci: CI holds itself to about 90 concurrent jobs; every run waits for room and main goes first (AST-030 FR16, DEC-16) (#9006)

Cindy Zhangeae4b9eb5079
diff --git a/.github/actions/ci-admission/action.yml b/.github/actions/ci-admission/action.yml
new file mode 100644
index 0000000000..5d1ff2f8de
--- /dev/null
+++ b/.github/actions/ci-admission/action.yml
@@ -0,0 +1,189 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+# Admits a whole CI run under CI's ceiling of about ninety concurrent jobs
+# (spec:AST-030 FR16, DEC-16). GitHub has no repository-wide job limit to set
+# (a `concurrency` group serializes runs, it does not count jobs), so each run
+# waits for room before its jobs start:
+#
+# - ci.yml's `admission` job, which every other ci.yml job needs, and the Main
+# workflow's `main-commit` job run this first. A step that uses this action
+# MUST be named "Wait for room under the CI ceiling": a waiting `main` run is
+# found by that name.
+# - A run starts once the other active runs' estimated jobs plus `peak` fit
+# under the ceiling. Small workflows that are not admitted (one or two slim
+# jobs a run) always count at least their measured most at once, so the room
+# they can still take is kept free. A pull-request run (`main: false`) also
+# waits while a
+# `main` full check or release re-check is waiting, so `main` fits first;
+# pull-request runs never wait for each other.
+# - It waits at most `max-wait-minutes` (fifteen for `main`, twelve for a pull
+# request, inside its fifteen-minute job budget), looking at even intervals
+# plus a random 0-20 s so runs that look together spread out, and then
+# starts.
+# - Each CI or Main run counts its live jobs, read once per look. A
+# pull-request run still waiting here counts only that waiting job, so
+# waiting runs never hold each other back by more than they use; a waiting
+# `main` run counts its whole peak. A run admitted in the last three minutes
+# counts at least its planned most until its jobs appear. Every other
+# workflow's run counts an estimate.
+# - A look costs two run listings plus one call per active CI or Main run, and
+# a run looks at most `max-looks` times: twice for a pull request (at once and
+# after its longest wait), every two minutes for the rare `main` run. When the
+# repository's API budget is low, the run starts rather than spend it.
+# - A pull request that may not run CI (a draft, or a fork without `ci:run`)
+# starts at once, so its required contexts report their failure (FR17).
+# - A failed lookup, a rate limit included, starts the run.
+
+name: CI admission
+description: Waits until a CI run's jobs fit under CI's ceiling.
+
+inputs:
+ peak:
+ description: The most jobs this run holds at once.
+ required: true
+ main:
+ description: "'true' for a main full check or release re-check, which does not wait for other main runs."
+ required: true
+ max-wait-minutes:
+ description: The longest this run waits before it starts anyway.
+ required: false
+ default: '15'
+ max-looks:
+ description: The most times this run looks for room.
+ required: false
+ default: '8'
+ label-legs:
+ description: JSON map of a pull-request label to the jobs it adds to `peak`.
+ required: false
+ default: '{}'
+
+runs:
+ using: composite
+ steps:
+ - uses: actions/github-script@v9
+ env:
+ PEAK: ${{ inputs.peak }}
+ MAIN: ${{ inputs.main }}
+ LABEL_LEGS: ${{ inputs.label-legs }}
+ MAX_WAIT_MINUTES: ${{ inputs.max-wait-minutes }}
+ MAX_LOOKS: ${{ inputs.max-looks }}
+ with:
+ retries: 3
+ script: |
+ const CI_CEILING = 90;
+ // Below this many API calls left this hour, a run starts rather than
+ // spend the budget every job shares.
+ const BUDGET_FLOOR = 1500;
+ const JITTER_MS = 20_000;
+ const MAX_WAIT_MS = Number(process.env.MAX_WAIT_MINUTES || '15') * 60_000;
+ const MAX_LOOKS = Math.max(1, Number(process.env.MAX_LOOKS || '8'));
+ const LOOK_MS = MAX_LOOKS > 1 ? (MAX_WAIT_MS - JITTER_MS) / (MAX_LOOKS - 1) : MAX_WAIT_MS;
+ const STEP = 'Wait for room under the CI ceiling';
+ // The most jobs a run holds at once, by workflow: ci.yml's
+ // release-check and Main's unit run from their `peak`
+ // (ci-admission.test.mjs), a pull-request ci.yml run from its
+ // measured most, every other workflow's run one or two slim jobs.
+ const ESTIMATE = {
+ '.github/workflows/ci.yml': run => (run.event === 'workflow_dispatch' ? 36 : 16),
+ '.github/workflows/deploy.yml': () => 14,
+ '.github/workflows/review-signal.yml': () => 2,
+ };
+ const estimate = run => (ESTIMATE[run.path] ?? (() => 1))(run);
+ // The most jobs small, unadmitted workflows ran at once, measured
+ // over a busy evening (spec:AST-030 DEC-16).
+ const SMALL_MOST = 18;
+ const ADMITTED = ['.github/workflows/ci.yml', '.github/workflows/deploy.yml'];
+ const admitted = run => ADMITTED.includes(run.path);
+ const LIVE = ['in_progress', 'queued', 'waiting', 'pending'];
+ const JUST_ADMITTED_MS = 3 * 60_000;
+ const isMain = run =>
+ ['push', 'schedule', 'workflow_dispatch'].includes(run.event) &&
+ ['.github/workflows/ci.yml', '.github/workflows/deploy.yml'].includes(run.path);
+
+ let peak = Number(process.env.PEAK);
+ if (!Number.isInteger(peak) || peak < 1) {
+ throw new Error(`peak must be a positive integer, got "${process.env.PEAK}".`);
+ }
+ const main = process.env.MAIN === 'true';
+ const pr = context.payload.pull_request;
+ if (pr != null) {
+ const labels = (pr.labels ?? []).map(label => label.name);
+ const fork = pr.head?.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`;
+ if (pr.draft || (fork && !labels.includes('ci:run'))) {
+ core.info('This pull request runs no CI yet; nothing to admit.');
+ return;
+ }
+ const extra = JSON.parse(process.env.LABEL_LEGS || '{}');
+ for (const label of labels) peak += extra[label] ?? 0;
+ }
+
+ const started = Date.now();
+ let calls = 0;
+ try {
+ for (let look = 1; ; look += 1) {
+ const seen = new Set();
+ let large = 0;
+ let small = 0;
+ let mainWaiting = false;
+ for (const status of ['in_progress', 'queued']) {
+ calls += 1;
+ const {data, headers} = await github.rest.actions.listWorkflowRunsForRepo({
+ ...context.repo, status, per_page: 100,
+ });
+ const left = Number(headers?.['x-ratelimit-remaining']);
+ if (Number.isFinite(left) && left < BUDGET_FLOOR) {
+ core.warning(`Only ${left} API calls left this hour; starting without spending them.`);
+ return;
+ }
+ for (const run of data.workflow_runs) {
+ if (seen.has(run.id) || run.id === context.runId) continue;
+ seen.add(run.id);
+ if (!admitted(run)) {
+ small += estimate(run);
+ continue;
+ }
+ calls += 1;
+ const {data: {jobs}} = await github.rest.actions.listJobsForWorkflowRun({
+ ...context.repo, run_id: run.id, filter: 'latest', per_page: 100,
+ });
+ const wait = jobs
+ .flatMap(job => job.steps ?? [])
+ .find(step => step.name === STEP);
+ if (wait?.status === 'in_progress') {
+ // Still waiting for room. A pull-request run holds only
+ // the job that waits; a `main` run holds its whole peak,
+ // ahead of this one.
+ if (isMain(run)) {
+ large += estimate(run);
+ if (!main) mainWaiting = true;
+ } else {
+ large += 1;
+ }
+ continue;
+ }
+ const live = jobs.filter(job => LIVE.includes(job.status)).length;
+ const admittedAt = Date.parse(wait?.completed_at ?? '');
+ large += Date.now() - admittedAt < JUST_ADMITTED_MS ? Math.max(live, estimate(run)) : live;
+ }
+ }
+ const others = large + Math.max(small, SMALL_MOST);
+ if (others + peak <= CI_CEILING && !mainWaiting) {
+ core.info(`Room under the CI ceiling: about ${others} other jobs + ${peak} <= ${CI_CEILING}.`);
+ return;
+ }
+ // The time left decides, not the look's own API time: a slow
+ // look still waits the rest of the way for its next one.
+ const left = MAX_WAIT_MS - (Date.now() - started);
+ const wait = Math.min(LOOK_MS + Math.floor(Math.random() * JITTER_MS), left);
+ if (look >= MAX_LOOKS || wait <= 0) {
+ core.warning(`Still no room after ${MAX_WAIT_MS / 60_000} minutes (about ${others} other jobs${mainWaiting ? ', a main check waiting' : ''}); starting.`);
+ return;
+ }
+ core.info(`Waiting for room: about ${others} other jobs + ${peak}${mainWaiting ? ', a main check waiting' : ''}.`);
+ await new Promise(resolve => setTimeout(resolve, wait));
+ }
+ } catch (error) {
+ core.warning(`Room under the CI ceiling could not be checked (${error.message}); starting.`);
+ } finally {
+ core.info(`CI admission: ${calls} API calls.`);
+ }
diff --git a/.github/scripts/ci-admission.test.mjs b/.github/scripts/ci-admission.test.mjs
new file mode 100644
index 0000000000..26add0ea71
--- /dev/null
+++ b/.github/scripts/ci-admission.test.mjs
@@ -0,0 +1,542 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every CI and Main run waits for room under CI's ceiling before its
+ * jobs start (.github/actions/ci-admission, spec:AST-030 FR16, DEC-16).
+ * @input The action, the CI and Main workflows, and a stubbed GitHub API
+ * @output Where each run waits, that waiting can never skip or fail a required
+ * check, each run's `peak` against the jobs it can hold, and when a run
+ * starts, yields to `main`, or gives up waiting
+ * @position Node contracts for the run-level ceiling; heavy-caps-action.test.mjs
+ * keeps the per-author limits
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import yaml from 'yaml';
+import {PR_CI_GATE} from './ci-pr-gate.mjs';
+
+const root = path.resolve(import.meta.dirname, '../..');
+const read = file => yaml.parse(fs.readFileSync(path.join(root, file), 'utf8'));
+const action = read('.github/actions/ci-admission/action.yml');
+const ci = read('.github/workflows/ci.yml');
+const main = read('.github/workflows/deploy.yml');
+const script = action.runs.steps[0].with.script;
+const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+const STEP = 'Wait for room under the CI ceiling';
+const CEILING = Number(/const CI_CEILING = (\d+);/.exec(script)[1]);
+const needsOf = job => [job.needs ?? []].flat();
+const stepOf = job => job.steps.find(step => step.name === STEP);
+const estimateOf = workflow =>
+ new RegExp(`'\\.github/workflows/${workflow}': [^\\n]*`).exec(script)[0];
+
+/** Legs a job runs for an event: its matrix size, or one. */
+function legs(job, event = 'workflow_dispatch') {
+ const matrix = job.strategy?.matrix;
+ if (matrix == null) return 1;
+ return Object.values(matrix)
+ .map(value => {
+ if (Array.isArray(value)) return value;
+ // A release-check's wider legs (spec:AST-030): one branch per event.
+ const split =
+ /fromJSON\(github\.event_name == 'workflow_dispatch' && '([^']*)' \|\| '([^']*)'\)/.exec(
+ String(value),
+ );
+ if (!split) return [value];
+ return JSON.parse(event === 'workflow_dispatch' ? split[1] : split[2]);
+ })
+ .reduce((product, list) => product * list.length, 1);
+}
+
+describe('where runs wait', () => {
+ const admission = ci.jobs.admission;
+ const wait = stepOf(admission);
+
+ it('admits a whole ci.yml run in a first slim job that every other job needs', () => {
+ expect(Object.keys(ci.jobs)[0]).toBe('admission');
+ expect(admission['runs-on']).toBe('ubuntu-slim');
+ expect(admission.permissions).toEqual({actions: 'read', contents: 'read'});
+ expect(wait.uses).toBe('./.ci-admission/.github/actions/ci-admission');
+ // Directly, or through the jobs it needs.
+ const reaches = id =>
+ needsOf(ci.jobs[id]).some(need => need === 'admission' || reaches(need));
+ for (const id of Object.keys(ci.jobs)) {
+ if (id !== 'admission') expect(reaches(id), id).toBe(true);
+ }
+ });
+
+ it('skips only with every other job, and never fails, so every job and required check decides as before', () => {
+ // The pull-request gate every job carries: a draft or an unlabelled fork
+ // runs no CI (FR17). Every other event is admitted.
+ expect(admission.if).toBe(PR_CI_GATE);
+ expect(needsOf(admission)).toEqual([]);
+ // Whatever the step does, a lookup error or its own time limit, the job
+ // succeeds, and it finishes before the job's own limit.
+ expect(wait['continue-on-error']).toBe(true);
+ const limit = (value, event) => {
+ const split = /&& (\d+) \|\| (\d+)/.exec(String(value));
+ return split
+ ? Number(split[event === 'workflow_dispatch' ? 1 : 2])
+ : Number(value);
+ };
+ for (const event of ['workflow_dispatch', 'pull_request']) {
+ // The wait ends before the step's limit, and the step's before the job's.
+ expect(limit(wait.with['max-wait-minutes'], event)).toBeLessThan(
+ limit(wait['timeout-minutes'], event),
+ );
+ expect(limit(wait['timeout-minutes'], event)).toBeLessThan(
+ limit(admission['timeout-minutes'], event),
+ );
+ }
+ // A pull request's admission stays inside the fifteen-minute job budget.
+ expect(
+ limit(admission['timeout-minutes'], 'pull_request'),
+ ).toBeLessThanOrEqual(15);
+ expect(limit(wait.with['max-wait-minutes'], 'workflow_dispatch')).toBe(15);
+ // A pull request looks twice; the rare main run every two minutes.
+ expect(limit(wait.with['max-looks'], 'pull_request')).toBe(2);
+ expect(limit(wait.with['max-looks'], 'workflow_dispatch')).toBe(8);
+ expect(admission.steps.filter(step => step !== wait)).toEqual([
+ expect.objectContaining({uses: 'actions/checkout@v7'}),
+ ]);
+ });
+
+ it('leaves every required context reporting on drafts, forks, deferred pushes and spec-only pull requests', () => {
+ // build, test and docsite-test, and the build-storybook and typecheck
+ // results build reads, each state a status rule and never read admission's
+ // result, so admission can change none of their verdicts short of a
+ // cancelled run. Admission itself returns at once for a draft or an
+ // unlabelled fork (below), and admits every other pull request, a
+ // deferred push or a spec-only change included, like any run.
+ for (const id of [
+ 'build',
+ 'test',
+ 'docsite-test',
+ 'build-storybook',
+ 'typecheck',
+ ]) {
+ const condition = String(ci.jobs[id].if);
+ expect(condition, id).toMatch(/\b(always|cancelled)\(\)/);
+ expect(condition, id).not.toContain('needs.admission');
+ }
+ // lint and review-required are written by workflows admission does not touch.
+ for (const file of ['lint.yml', 'review-signal.yml', 'review-clear.yml']) {
+ expect(
+ fs.readFileSync(path.join(root, '.github/workflows', file), 'utf8'),
+ ).not.toContain('ci-admission');
+ }
+ });
+
+ it("admits Main's unit run in main-commit, which every other job needs", () => {
+ const job = main.jobs['main-commit'];
+ const step = stepOf(job);
+ expect(step.uses).toBe('./.ci-admission/.github/actions/ci-admission');
+ expect(step.with.main).toBe(true);
+ expect(step.with['max-wait-minutes']).toBeUndefined(); // fifteen
+ expect(step['continue-on-error']).toBe(true);
+ expect(job.permissions.actions).toBe('read');
+ // Directly, or through the lanes it joins.
+ const reaches = id =>
+ needsOf(main.jobs[id]).some(
+ need => need === 'main-commit' || reaches(need),
+ );
+ for (const id of Object.keys(main.jobs)) {
+ if (id !== 'main-commit') expect(reaches(id), id).toBe(true);
+ }
+ });
+});
+
+describe('peaks', () => {
+ it('gives a release-check a peak that covers every job it can hold at once', () => {
+ // A release-check runs the jobs its join needs. A job every leg needs
+ // has finished before the legs start, and each join needs legs that have
+ // finished, so the most held at once is every leg plus the other first
+ // jobs.
+ const closure = new Set();
+ const visit = name => {
+ for (const need of needsOf(ci.jobs[name])) {
+ if (
+ ['maintenance-request', 'admission'].includes(need) ||
+ closure.has(need)
+ )
+ continue;
+ closure.add(need);
+ visit(need);
+ }
+ };
+ visit('release-check');
+ const inner = name =>
+ needsOf(ci.jobs[name]).filter(need => closure.has(need));
+ const first = [...closure].filter(name => inner(name).length === 0);
+ const wave = [...closure].filter(
+ name =>
+ inner(name).length > 0 &&
+ inner(name).every(need => first.includes(need)),
+ );
+ const before = first.filter(name =>
+ wave.every(job => inner(job).includes(name)),
+ );
+ expect(before).toContain('build-storybook');
+ const held = [...wave, ...first.filter(name => !before.includes(name))]
+ .map(name => legs(ci.jobs[name]))
+ .reduce((sum, count) => sum + count, 0);
+ const peak = Number(
+ /&& (\d+) \|\|/.exec(stepOf(ci.jobs.admission).with.peak)[1],
+ );
+ expect(peak).toBeGreaterThanOrEqual(held);
+ expect(peak).toBeLessThanOrEqual(CEILING);
+ // Other runs count a running release-check at the same peak.
+ expect(estimateOf('ci.yml')).toContain(`'workflow_dispatch' ? ${peak} :`);
+ });
+
+ it("gives Main's unit run a peak that covers all its jobs beside main-commit", () => {
+ const held = Object.keys(main.jobs)
+ .filter(name => name !== 'main-commit' && name !== 'test')
+ .map(name => legs(main.jobs[name]))
+ .reduce((sum, count) => sum + count, 0);
+ const peak = stepOf(main.jobs['main-commit']).with.peak;
+ expect(peak).toBeGreaterThanOrEqual(held);
+ expect(estimateOf('deploy.yml')).toContain(`() => ${peak},`);
+ });
+
+ it('gives a pull request a peak that covers every job it starts at once', () => {
+ // The jobs that need only admission start together the moment it ends.
+ const first = Object.keys(ci.jobs).filter(
+ name =>
+ name !== 'admission' &&
+ needsOf(ci.jobs[name]).every(need => need === 'admission'),
+ );
+ const onPullRequest = first.filter(name => {
+ const condition = String(ci.jobs[name].if ?? '');
+ return !/^(\$\{\{\s*)?(always\(\) && )?github\.event_name == 'workflow_dispatch'/.test(
+ condition,
+ );
+ });
+ const started = onPullRequest
+ .map(name => legs(ci.jobs[name], 'pull_request'))
+ .reduce((sum, count) => sum + count, 0);
+ const peak = Number(
+ /\|\| (\d+) \}\}$/.exec(stepOf(ci.jobs.admission).with.peak)[1],
+ );
+ expect(peak).toBeGreaterThanOrEqual(started);
+ expect(estimateOf('ci.yml')).toContain(`: ${peak}),`);
+ });
+
+ it('adds the jobs each opt-in label brings to a pull request', () => {
+ const pull = job => legs(ci.jobs[job], 'pull_request');
+ expect(JSON.parse(stepOf(ci.jobs.admission).with['label-legs'])).toEqual({
+ 'ci:run-visual': pull('visual-scout') + pull('pr-visual'),
+ 'ci:run-rtl':
+ pull('pr-rtl-shard') + pull('pr-rtl-merge') + pull('pr-rtl'),
+ 'ci:run-a11y':
+ pull('pr-a11y-guards') + pull('pr-a11y-specs') + pull('pr-a11y'),
+ });
+ });
+});
+
+describe('ci admission', () => {
+ afterEach(() => vi.useRealTimers());
+ afterEach(() => vi.restoreAllMocks());
+ const OWN = 1;
+ const NOW = Date.parse('2026-11-01T02:00:00Z');
+ const ago = minutes => new Date(NOW - minutes * 60_000).toISOString();
+ const busy = count =>
+ Array.from({length: count}, () => ({status: 'in_progress', steps: []}));
+ /** A CI or Main run admitted `admittedMinutesAgo` ago with `live` jobs running. */
+ const admittedRun = (
+ id,
+ live,
+ {
+ event = 'pull_request',
+ path = '.github/workflows/ci.yml',
+ admittedMinutesAgo = 10,
+ } = {},
+ ) => ({
+ id,
+ status: 'in_progress',
+ event,
+ path,
+ jobs: [
+ {
+ status: 'completed',
+ steps: [
+ {
+ name: STEP,
+ status: 'completed',
+ completed_at: ago(admittedMinutesAgo),
+ },
+ ],
+ },
+ ...busy(live),
+ ],
+ });
+ /** A CI or Main run still waiting in its admission step. */
+ const waitingRun = (
+ id,
+ {event = 'pull_request', path = '.github/workflows/ci.yml'} = {},
+ ) => ({
+ id,
+ status: 'in_progress',
+ event,
+ path,
+ jobs: [
+ {status: 'in_progress', steps: [{name: STEP, status: 'in_progress'}]},
+ ],
+ });
+ const slim = id => ({
+ id,
+ status: 'in_progress',
+ event: 'workflow_run',
+ path: '.github/workflows/pr-comment.yml',
+ });
+ const prs = (count, live = 12) =>
+ Array.from({length: count}, (_, i) => admittedRun(10 + i, live));
+ const slims = count => Array.from({length: count}, (_, i) => slim(500 + i));
+
+ async function admit({
+ active = [],
+ peak = 12,
+ isMain = false,
+ labels = [],
+ pull = {},
+ error,
+ maxWait = 15,
+ maxLooks = 8,
+ budget = 4000,
+ latencyMs = 0,
+ random = 0,
+ } = {}) {
+ vi.useFakeTimers({now: NOW});
+ vi.spyOn(Math, 'random').mockReturnValue(random);
+ const lookTimes = [];
+ let looks = 0;
+ let calls = 0;
+ const logs = {info: [], warning: []};
+ const runs = () => (typeof active === 'function' ? active(looks) : active);
+ const github = {
+ rest: {
+ actions: {
+ listWorkflowRunsForRepo: async ({status, event, per_page}) => {
+ if (error) throw error;
+ expect([event, per_page]).toEqual([undefined, 100]);
+ calls += 1;
+ if (latencyMs > 0)
+ await new Promise(resolve => setTimeout(resolve, latencyMs));
+ if (status === 'in_progress') {
+ looks += 1;
+ lookTimes.push(Date.now() - NOW);
+ }
+ return {
+ data: {
+ workflow_runs: runs().filter(run => run.status === status),
+ },
+ headers: {'x-ratelimit-remaining': String(budget)},
+ };
+ },
+ listJobsForWorkflowRun: async ({run_id, per_page}) => {
+ expect(per_page).toBe(100);
+ calls += 1;
+ return {
+ data: {jobs: runs().find(run => run.id === run_id).jobs ?? []},
+ };
+ },
+ },
+ },
+ };
+ const core = {
+ info: message => logs.info.push(message),
+ warning: message => logs.warning.push(message),
+ };
+ const context = {
+ repo: {owner: 'o', repo: 'r'},
+ runId: OWN,
+ payload: isMain
+ ? {}
+ : {
+ pull_request: {
+ draft: false,
+ head: {repo: {full_name: 'o/r'}},
+ labels: labels.map(name => ({name})),
+ ...pull,
+ },
+ },
+ };
+ Object.assign(process.env, {
+ PEAK: String(peak),
+ MAIN: String(isMain),
+ LABEL_LEGS: '{"ci:run-visual": 6}',
+ MAX_WAIT_MINUTES: String(maxWait),
+ MAX_LOOKS: String(maxLooks),
+ });
+ const done = new AsyncFunction('github', 'context', 'core', script)(
+ github,
+ context,
+ core,
+ );
+ // Observed here; `await done` below still rethrows a failure.
+ done.catch(() => {});
+ await vi.advanceTimersByTimeAsync(20 * 60_000);
+ await done;
+ return {...logs, looks, calls, lookTimes};
+ }
+
+ it("admits at once at today's load: 56 live jobs and many pull-request runs waiting", async () => {
+ // 2026-11-01 ~01:50Z: 56 jobs ran, a dozen of them the waiting jobs of
+ // pull-request runs. The first estimate counted each waiting run at 12 and
+ // saw about 180 jobs, so every run waited out its twelve minutes. Counting
+ // what runs: 33 + 11 + 12 waiting jobs + 18 kept for small workflows + this
+ // run's 16 = 90.
+ const active = [
+ ...prs(3, 11),
+ admittedRun(30, 11, {
+ event: 'push',
+ path: '.github/workflows/deploy.yml',
+ }),
+ ...Array.from({length: 12}, (_, i) => waitingRun(40 + i)),
+ ...slims(8),
+ ];
+ const result = await admit({active, peak: 16, maxWait: 12, maxLooks: 2});
+ expect(result.looks).toBe(1);
+ expect(result.warning).toEqual([]);
+ // Two run listings plus one jobs call per CI or Main run.
+ expect(result.calls).toBe(2 + 3 + 1 + 12);
+ });
+
+ it('counts live jobs, and a run admitted in the last three minutes at least at its most', async () => {
+ // 4 x 12 live + 18 small + 13 = 79: room.
+ expect((await admit({active: prs(4), peak: 13})).looks).toBe(1);
+ // A just-admitted run with 2 jobs so far counts its planned 16 (95); a long-running one, 2 (81).
+ const fresh = admittedRun(60, 2, {admittedMinutesAgo: 1});
+ const old = admittedRun(60, 2, {admittedMinutesAgo: 9});
+ expect(
+ (await admit({active: [...prs(4), fresh], peak: 13})).looks,
+ ).toBeGreaterThan(1);
+ expect((await admit({active: [...prs(4), old], peak: 13})).looks).toBe(1);
+ });
+
+ it("keeps room for small workflows' measured most", async () => {
+ expect((await admit({active: [...prs(5), ...slims(18)]})).looks).toBe(1);
+ expect(
+ (await admit({active: [...prs(5), ...slims(19)]})).looks,
+ ).toBeGreaterThan(1);
+ });
+
+ it('looks twice for a pull request, at once and after its longest wait', async () => {
+ const full = prs(6); // 72 + 18 + 12 > 90
+ const pull = await admit({active: full, maxWait: 12, maxLooks: 2});
+ expect(pull.looks).toBe(2);
+ expect(pull.warning[0]).toContain('after 12 minutes');
+ const freed = await admit({
+ active: look => (look < 2 ? full : full.slice(1)),
+ maxWait: 12,
+ maxLooks: 2,
+ });
+ expect(freed).toMatchObject({looks: 2, warning: []});
+ });
+
+ it('waits out its second look even when the first is slow and the jitter long', async () => {
+ // 8 s per run listing and a jitter of almost 20 s: the second look still
+ // comes, about twelve minutes in, rather than giving up after one.
+ const pull = await admit({
+ active: prs(6),
+ maxWait: 12,
+ maxLooks: 2,
+ latencyMs: 8_000,
+ random: 0.999,
+ });
+ expect(pull.looks).toBe(2);
+ expect(pull.lookTimes[1]).toBeGreaterThan(11 * 60_000);
+ // Recorded once its first listing returns, 8 s after the look began.
+ expect(pull.lookTimes[1]).toBeLessThanOrEqual(12 * 60_000 + 8_000);
+ });
+
+ it('looks every two minutes for a main run, for at most fifteen', async () => {
+ const full = prs(5); // 60 + 18 + 36 > 90
+ const stuck = await admit({active: full, isMain: true, peak: 36});
+ expect(stuck.looks).toBe(8);
+ expect(stuck.warning[0]).toContain('after 15 minutes');
+ const freed = await admit({
+ active: look => (look < 3 ? full : full.slice(3)),
+ isMain: true,
+ peak: 36,
+ });
+ expect(freed.looks).toBe(3);
+ });
+
+ it('lets a waiting main run go first, counting its whole peak; never waits for a pull-request run', async () => {
+ const mainWaiting = waitingRun(70, {event: 'workflow_dispatch'});
+ const held = await admit({
+ active: look =>
+ look < 2
+ ? [mainWaiting]
+ : [admittedRun(70, 30, {event: 'workflow_dispatch'})],
+ maxWait: 12,
+ maxLooks: 2,
+ });
+ expect(held.looks).toBe(2);
+ // Other pull-request runs waiting for room hold only their waiting jobs:
+ // 48 + 8 waiting + 18 + 16 = 90 fits; a ninth waiting run does not.
+ const waiting = count =>
+ Array.from({length: count}, (_, i) => waitingRun(80 + i));
+ expect(
+ (await admit({active: [...prs(4), ...waiting(8)], peak: 16})).looks,
+ ).toBe(1);
+ expect(
+ (await admit({active: [...prs(4), ...waiting(9)], peak: 16})).looks,
+ ).toBeGreaterThan(1);
+ // A main run does not wait for another main run's wait, but counts its peak.
+ expect(
+ (
+ await admit({
+ isMain: true,
+ peak: 36,
+ active: [
+ waitingRun(73, {
+ event: 'schedule',
+ path: '.github/workflows/deploy.yml',
+ }),
+ ],
+ })
+ ).looks,
+ ).toBe(1);
+ });
+
+ it("adds the jobs a pull request's opt-in labels bring", async () => {
+ // 4 runs x 12 + 25 slim jobs: 73 + 12 fits; + 6 for the label does not.
+ const active = [...prs(4), ...slims(25)];
+ expect((await admit({active})).looks).toBe(1);
+ expect(
+ (await admit({active, labels: ['ci:run-visual']})).looks,
+ ).toBeGreaterThan(1);
+ });
+
+ it('starts at once, with no API calls, for a pull request that runs no CI yet', async () => {
+ const full = prs(8);
+ for (const pull of [{draft: true}, {head: {repo: {full_name: 'fork/r'}}}]) {
+ expect(await admit({active: full, pull})).toMatchObject({
+ looks: 0,
+ calls: 0,
+ });
+ }
+ const labelled = await admit({
+ active: full,
+ labels: ['ci:run'],
+ pull: {head: {repo: {full_name: 'fork/r'}}},
+ });
+ expect(labelled.looks).toBeGreaterThan(1);
+ });
+
+ it('starts rather than spend a low API budget, and when the API cannot be read', async () => {
+ const low = await admit({active: prs(8), budget: 1499});
+ expect(low).toMatchObject({looks: 1, calls: 1});
+ expect(low.warning[0]).toContain('API calls left');
+ const failed = await admit({error: new Error('API rate limit exceeded')});
+ expect(failed.warning[0]).toContain('could not be checked');
+ });
+
+ it('refuses a peak that is not a positive integer', async () => {
+ await expect(admit({peak: 0})).rejects.toThrow('positive integer');
+ });
+});
diff --git a/.github/scripts/ci-docsite-browser.test.mjs b/.github/scripts/ci-docsite-browser.test.mjs
index dd8e0c6915..cea8ec4931 100644
--- a/.github/scripts/ci-docsite-browser.test.mjs
+++ b/.github/scripts/ci-docsite-browser.test.mjs
@@ -29,13 +29,14 @@ describe('docsite-test', () => {
it('is one job that builds the docsite once and runs both suites on it', () => {
expect(jobs['docsite-data']).toBeUndefined();
expect(jobs['docsite-browser']).toBeUndefined();
- expect(owner.needs).toBeUndefined();
+ // Only CI's run admission, which never skips (ci-admission.test.mjs).
+ expect(owner.needs).toEqual(['admission']);
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.
expect(owner.if).toBe(
gated(
- "${{ github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') }}",
+ "${{ github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled() }}",
PR_REPORT_GATE,
),
);
diff --git a/.github/scripts/release-check-workflow.test.mjs b/.github/scripts/release-check-workflow.test.mjs
index a7d17e1b2c..6f2e69f945 100644
--- a/.github/scripts/release-check-workflow.test.mjs
+++ b/.github/scripts/release-check-workflow.test.mjs
@@ -23,6 +23,8 @@ const packageJson = JSON.parse(
fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
);
const releaseJobs = [
+ // Admits every CI run under CI's ceiling (ci-admission.test.mjs).
+ 'admission',
'release-authority',
'test-registry-e2e',
// Decides the pull-request opt-ins; on a release check it opts nothing in
diff --git a/.github/scripts/shadcn-registry-ci.test.mjs b/.github/scripts/shadcn-registry-ci.test.mjs
index 8dddd1a860..5ddc3f4cb9 100644
--- a/.github/scripts/shadcn-registry-ci.test.mjs
+++ b/.github/scripts/shadcn-registry-ci.test.mjs
@@ -36,7 +36,8 @@ function runLines() {
describe('ShadCN registry CI contract', () => {
it('runs for release-check and gates it, not every pull request', () => {
- expect(job.needs).toBeUndefined();
+ // Only CI's run admission (ci-admission.test.mjs).
+ expect(job.needs).toEqual(['admission']);
expect(job.if).toBe(
"github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'",
);
diff --git a/.github/scripts/spec-owner-workflow.test.mjs b/.github/scripts/spec-owner-workflow.test.mjs
index b42dde8dc5..521a4f385f 100644
--- a/.github/scripts/spec-owner-workflow.test.mjs
+++ b/.github/scripts/spec-owner-workflow.test.mjs
@@ -223,7 +223,7 @@ describe('spec-only workflow contract', () => {
it('fails closed when file APIs are truncated or scope classification fails', () => {
const ci = read('.github/workflows/ci.yml');
expect(ci).toContain(
- `if: ${gated("${{ github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') }}", PR_REPORT_GATE)}`,
+ `if: ${gated("${{ github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled() }}", PR_REPORT_GATE)}`,
);
const action = read('.github/actions/test-scope/action.yml');
expect(action).toContain(
diff --git a/.github/scripts/visual-maintenance-workflow.test.mjs b/.github/scripts/visual-maintenance-workflow.test.mjs
index 2872e9c4c3..94c5ac275a 100644
--- a/.github/scripts/visual-maintenance-workflow.test.mjs
+++ b/.github/scripts/visual-maintenance-workflow.test.mjs
@@ -103,7 +103,9 @@ describe('CI baseline maintenance routing', () => {
it('does not run non-maintenance CI jobs for capture', () => {
for (const [name, job] of Object.entries(workflow.jobs)) {
- if (['maintenance-request', 'pr-visual'].includes(name)) continue;
+ // admission admits every run, a capture's included (ci-admission.test.mjs).
+ if (['maintenance-request', 'pr-visual', 'admission'].includes(name))
+ continue;
expect(
runs(job, {operation: 'capture', needs: dependencies(job)}),
name,
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 82896ac690..a0f597eb67 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -82,7 +82,43 @@ concurrency:
cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
jobs:
+ # Admits the whole run under CI's ceiling of about ninety concurrent jobs
+ # (spec:AST-030 FR16, DEC-16). Every job here needs this one, directly or
+ # through the jobs it needs. Like every other job it skips for a draft or an
+ # unlabelled fork, which run no CI (FR17); the required contexts still report
+ # through their own status rules. Otherwise it never fails, so each job's own
+ # condition decides exactly as before. `peak` is the most jobs a run holds at once: a
+ # release-check's from its legs, a pull request's from its measured most plus
+ # the suites its labels opt into (ci-admission.test.mjs). A pull request
+ # waits at most twelve minutes, inside the fifteen-minute job budget.
+ 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')))
+ runs-on: ubuntu-slim
+ timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 20 || 15 }}
+ permissions:
+ actions: read
+ contents: read
+ steps:
+ - name: Check out the admission action
+ uses: actions/checkout@v7
+ with:
+ sparse-checkout: .github/actions/ci-admission
+ path: .ci-admission
+ persist-credentials: false
+
+ - name: Wait for room under the CI ceiling
+ uses: ./.ci-admission/.github/actions/ci-admission
+ continue-on-error: true
+ timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 16 || 13 }}
+ with:
+ peak: ${{ github.event_name == 'workflow_dispatch' && 36 || 16 }}
+ main: ${{ github.event_name == 'workflow_dispatch' }}
+ max-wait-minutes: ${{ github.event_name == 'workflow_dispatch' && 15 || 12 }}
+ max-looks: ${{ github.event_name == 'workflow_dispatch' && 8 || 2 }}
+ label-legs: '{"ci:run-visual": 6, "ci:run-rtl": 9, "ci:run-a11y": 3}'
+
maintenance-request:
+ needs: [admission]
if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
runs-on: ubuntu-slim
steps:
@@ -99,6 +135,7 @@ jobs:
# Pull requests never run it: a release-branch pull request validates its
# own bump in release-bump, and every test job decides its own scope.
release-authority:
+ needs: [admission]
if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
runs-on: ubuntu-slim
permissions:
@@ -196,6 +233,7 @@ jobs:
# Generated-only version PR lane. It validates release bookkeeping in a few
# minutes; the merged branch head receives one full visual/a11y/RTL projection.
release-bump:
+ 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 == 'pull_request' && startsWith(github.base_ref, 'release/v')) }}
runs-on: 2-core-ubuntu-arm
timeout-minutes: 15
@@ -261,6 +299,7 @@ jobs:
release-merge-back:
name: release-merge-back
+ needs: [admission]
# Only a release merge-back branch has anything for this job to validate,
# so every other pull request skips it before the full-history checkout
# below (minutes on a larger runner). The step after the checkout still
@@ -359,7 +398,8 @@ jobs:
# only the production build has the opaque-origin sandbox at all. The
# spec-only lane validates spec records here, where it always has.
docsite-test:
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v')) }}
+ needs: [admission]
+ 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
timeout-minutes: 15
@@ -493,6 +533,7 @@ 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') }}
# 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
@@ -607,6 +648,7 @@ 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') }}
# One runner ran the Node project in ~12 minutes. Vitest's --shard splits
# the files across the legs; `test` joins them.
@@ -700,6 +742,7 @@ 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') }}
runs-on: ubuntu-slim
timeout-minutes: 5
@@ -757,6 +800,7 @@ jobs:
# docsite-only change.
test-registry-e2e:
name: test-registry-e2e (${{ matrix.leg }})
+ needs: [admission]
if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
# The preview and hidden production registries are generated and verified
# independently, so each gets its own leg (~9 minutes in one job).
@@ -885,6 +929,7 @@ 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') }}
runs-on: ubuntu-slim
timeout-minutes: 5
@@ -918,6 +963,7 @@ jobs:
await decideRunLabels({github, context, core});
build-storybook:
+ 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') && always() && !cancelled()) }}
# Every browser lane waits for this job, and the package builds and the
# Storybook build run side by side (build-packages-and-storybook.mjs).
@@ -1276,6 +1322,7 @@ jobs:
# ~1.5 minutes sooner. The build and release-check joins require this job,
# so a type error still fails both.
typecheck:
+ 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') && always() && !cancelled()) }}
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 }}
@@ -2086,6 +2133,7 @@ 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')
runs-on: ubuntu-24.04-arm
timeout-minutes: 15
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 5ff9cd6036..6d511abf16 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -43,6 +43,8 @@ jobs:
main-commit:
runs-on: ubuntu-slim
permissions:
+ # actions: read lets the admission step count CI's live jobs.
+ actions: read
contents: read
outputs:
sha: ${{ steps.resolve.outputs.sha }}
@@ -86,6 +88,24 @@ jobs:
}
core.setOutput('sha', sha);
+ # A `main` full check waits for room under CI's ceiling before its legs
+ # start (spec:AST-030 FR16, DEC-16); every other job here needs this one.
+ # `peak` is the most jobs this run holds at once (ci-admission.test.mjs).
+ - name: Check out the admission action
+ uses: actions/checkout@v7
+ with:
+ sparse-checkout: .github/actions/ci-admission
+ path: .ci-admission
+ persist-credentials: false
+
+ - name: Wait for room under the CI ceiling
+ uses: ./.ci-admission/.github/actions/ci-admission
+ continue-on-error: true
+ timeout-minutes: 16
+ with:
+ peak: 14
+ main: true
+
# Verify package.json exports match the source tree.
# Fails if exports are stale — run `node scripts/sync-exports.js` locally to fix.
sync-exports:
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index 3f05294096..0691c15cca 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -315,24 +315,31 @@ they are separately named.
request, the heavy browser suites (the interaction proofs and the Build
package's browser and fixture-contrast contracts) run only when the pull
request is among its author's fifteen oldest open non-draft pull requests and
- the author has had at most one hundred heavy runs that UTC day. A heavy run is a
- CI run on one of those pull requests in which a heavy suite ran; a cancelled
- run does not count, and neither does a run whose heavy suites were held.
- Pull requests from the shared agent login count per branch prefix, and that
- login as a whole is also held to its five oldest pull requests and forty
- heavy runs a day. Engineering owners listed in `.github/ENGOWNERS`, as the
- pull request's base commit lists them, are exempt from all of these limits,
- the shared login's included, and so are bot accounts. A held
- suite's check fails with "Queued behind your 15 oldest PRs: runs on a push
- once it is among them, or at the pre-merge re-run.", "Queued behind the
- shared login's 5 oldest PRs: runs on a push once it is among them, or at the
- pre-merge re-run." or "Daily heavy-run cap reached, runs tomorrow or at
- pre-merge.", so no pull request passes the required checks without its heavy
- suites. A re-run, which is the pre-merge restart, is exempt from both limits,
- and when the limits cannot be looked up the suite runs. Merge-queue entries,
- `main`, release checks and the visual, accessibility and RTL owners a
- maintainer opts a pull request into with their `ci:run-*` labels are
- unaffected.
+ the author has had at most one hundred heavy runs that UTC day. A heavy run is
+ a CI run on one of those pull requests in which a heavy suite ran; a cancelled
+ run does not count, and neither does a run whose heavy suites were held. Pull
+ requests from the shared agent login count per branch prefix, and that login
+ as a whole is also held to its five oldest pull requests and forty heavy runs
+ a day. Engineering owners listed in `.github/ENGOWNERS`, as the pull request's
+ base commit lists them, are exempt from all of these limits, the shared
+ login's included, and so are bot accounts. A held suite's check fails with
+ "Queued behind your 15 oldest PRs: runs on a push once it is among them, or at
+ the pre-merge re-run.", "Queued behind the shared login's 5 oldest PRs: runs
+ on a push once it is among them, or at the pre-merge re-run." or "Daily
+ heavy-run cap reached, runs tomorrow or at pre-merge.", so no pull request
+ passes the required checks without its heavy suites. A re-run, which is the
+ pre-merge restart, is exempt from both limits, and when the limits cannot be
+ looked up the suite runs. Merge-queue entries, `main`, release checks and the
+ visual, accessibility and RTL owners a maintainer opts a pull request into
+ with their `ci:run-*` labels are unaffected by these per-author limits. Every
+ run of the CI and Main workflows, of any event, waits for room before its jobs
+ start: it starts once the other active runs' estimated jobs plus its own most
+ fit under about ninety, and a pull-request run also waits while a `main` full
+ check, release re-check or baseline capture is waiting, looking twice on a
+ pull request, at once and after twelve minutes, and every two minutes for at
+ most fifteen for `main` (DEC-16). A pull request that may not run CI admits
+ nothing, and waiting never fails a job, so every required context reports as
+ before.
- **FR17 — A pull request runs CI when it is ready and a maintainer can vouch
for it.** A draft pull request runs no CI, and marking it ready for review
starts its pull-request run, which runs what the change reaches (FR13,
@@ -368,9 +375,10 @@ they are separately named.
inside the fifteen-minute job budget (DEC-17). A dispatch may name `sha`, a
commit in `main`'s history that has the size records the build lane keeps, and
every lane checks that commit out; without it the run validates `main`'s tip.
- A `sha` run waits for nothing and replaces nothing. One validation of `main`
- runs at a time and a newer one waits. Only a release re-check, which the
- workflow token sends with `recheck` and no `sha`, cancels the running
+ A `sha` run waits for no other validation and replaces nothing; like every
+ Main run, it waits for room under CI's ceiling (FR16). One validation of
+ `main` runs at a time and a newer one waits. Only a release re-check, which
+ the workflow token sends with `recheck` and no `sha`, cancels the running
validation, because the re-check validates `main`'s tip in full itself.
Pull-request legs keep their shape.
@@ -409,23 +417,23 @@ read change (FR14).
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR2 | classifier unit tests expose the surface set | knowledge; docsite; admitted tool; Core/Lab/Charts/Rich Text/Vega source; shared config; unknown | an unclassified path receives a specialized lane or a category has no check owner |
-| FR3–FR4 | workflow contract tests execute an isolated trusted-base classifier | valid base; missing merge base; missing matcher/registry; classifier self-change; merge group | PR-controlled policy grants a lane, or missing trust data skips checks |
-| FR5 | mixed-surface and incomplete-owner routing tests | spec+component; tooling+component; named surface without admitted lane; docsite+shared | one surface hides another owner or a named-but-incomplete surface skips broad CI |
-| FR6–FR8 | Node-tooling dependency, CI workflow, and trusted post-CI workflow tests | both admitted score-ledger paths; Sandbox projection imports; test/build joins; preview/visual publisher | UI/browser/build work or preview publication runs for the singleton tool set, an operational consumer is untested, a visual status stays pending, or a required context disappears |
-| FR9 | mutation-sensitive classifier and workflow fixtures | unknown path; rename from unknown; truncated list; package-specific public paths | weakening a fail-closed rule leaves the suite green |
-| FR10 | surface-admission and routing contract tests | existing surface; proposed surface with and without the full admission contract | a new surface adds lanes without its approved paths, commands, ownership, projections, and routing tests |
-| FR11 | surface owner, internal-job, and required-join contract tests | Build package browser behavior; CLI; theme-family broad fallback; mixed Core+CLI | a second owner is routed for one surface, an internal job masquerades as a lane, an owned failure misses its join, or an unrelated owner runs |
-| FR12 | Storybook visual-plan, canonical workflow, and repository-owner guard tests | PR scope; full-plan maintenance; report-only publication; deployment/a11y/RTL/vibe artifacts | another workflow captures or compares pixels, a renamed or aliased owner escapes the guard, or legitimate non-visual artifacts are rejected |
-| FR13 | classifier, workflow contract, component-analysis and RTL-scope tests | component change; shared module; Changeset beside code; infrastructure path; incomplete list; no build | an infrastructure path is scoped, a file-system guard test is skipped, a reverse dependent leaves visual/RTL or enters PR accessibility, or a full-suite event is narrowed |
-| FR14 | `workflow-paths.test.mjs` over every workflow | path allowlist; required-context workflow | a `paths-ignore`, a match-all or exclusion glob, or a path filter on a workflow that reports a required context fails |
-| FR15 | workflow contract and reconciler tests | ENGOWNER spec PR; owner command; other comment; fork review; non-spec PR | `review-required` succeeds while spec approval is missing, another workflow publishes a review context, a fork review starts the spec checks, or a non-command comment starts a runner |
-| FR16 | `heavy-caps-action.test.mjs` cap cases and heavy-job contract | sixteenth-oldest PR; 101st heavy run of the day, beside cancelled, light and other-branch runs; agent lane and its five-PR and forty-run backstops; an engineering owner, including the shared login past those backstops, a commented-out or trailing-comment handle and an unreadable roster; bot; the deciding run; re-run; failed lookup | a heavy suite that runs ahead of the author's fifteen oldest PRs, or past the daily cap, a capped job that passes, an engineering owner or a re-run that is held, or a roster read from the pull request's head fails |
-| 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 |
-| 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 |
-| FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver | 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 | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a `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 fails |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR2 | classifier unit tests expose the surface set | knowledge; docsite; admitted tool; Core/Lab/Charts/Rich Text/Vega source; shared config; unknown | an unclassified path receives a specialized lane or a category has no check owner |
+| FR3–FR4 | workflow contract tests execute an isolated trusted-base classifier | valid base; missing merge base; missing matcher/registry; classifier self-change; merge group | PR-controlled policy grants a lane, or missing trust data skips checks |
+| FR5 | mixed-surface and incomplete-owner routing tests | spec+component; tooling+component; named surface without admitted lane; docsite+shared | one surface hides another owner or a named-but-incomplete surface skips broad CI |
+| FR6–FR8 | Node-tooling dependency, CI workflow, and trusted post-CI workflow tests | both admitted score-ledger paths; Sandbox projection imports; test/build joins; preview/visual publisher | UI/browser/build work or preview publication runs for the singleton tool set, an operational consumer is untested, a visual status stays pending, or a required context disappears |
+| FR9 | mutation-sensitive classifier and workflow fixtures | unknown path; rename from unknown; truncated list; package-specific public paths | weakening a fail-closed rule leaves the suite green |
+| FR10 | surface-admission and routing contract tests | existing surface; proposed surface with and without the full admission contract | a new surface adds lanes without its approved paths, commands, ownership, projections, and routing tests |
+| FR11 | surface owner, internal-job, and required-join contract tests | Build package browser behavior; CLI; theme-family broad fallback; mixed Core+CLI | a second owner is routed for one surface, an internal job masquerades as a lane, an owned failure misses its join, or an unrelated owner runs |
+| FR12 | Storybook visual-plan, canonical workflow, and repository-owner guard tests | PR scope; full-plan maintenance; report-only publication; deployment/a11y/RTL/vibe artifacts | another workflow captures or compares pixels, a renamed or aliased owner escapes the guard, or legitimate non-visual artifacts are rejected |
+| FR13 | classifier, workflow contract, component-analysis and RTL-scope tests | component change; shared module; Changeset beside code; infrastructure path; incomplete list; no build | an infrastructure path is scoped, a file-system guard test is skipped, a reverse dependent leaves visual/RTL or enters PR accessibility, or a full-suite event is narrowed |
+| FR14 | `workflow-paths.test.mjs` over every workflow | path allowlist; required-context workflow | a `paths-ignore`, a match-all or exclusion glob, or a path filter on a workflow that reports a required context fails |
+| FR15 | workflow contract and reconciler tests | ENGOWNER spec PR; owner command; other comment; fork review; non-spec PR | `review-required` succeeds while spec approval is missing, another workflow publishes a review context, a fork review starts the spec checks, or a non-command comment starts a runner |
+| FR16 | `heavy-caps-action.test.mjs` cap cases and heavy-job contract; `ci-admission.test.mjs` | sixteenth-oldest PR; 101st heavy run of the day, beside cancelled, light and other-branch runs; agent lane and its five-PR and forty-run backstops; an engineering owner, including the shared login past those backstops, a commented-out or trailing-comment handle and an unreadable roster; bot; the deciding run; re-run; failed lookup; a run with room, without room, past its longest wait, beside a waiting `main` check, as a draft or unlabelled fork, with opt-in labels, beside small workflows past their measured most, and with the API unreadable; each workflow's most jobs; every required context's rule | a heavy suite that runs ahead of the author's fifteen oldest PRs, or past the daily cap, a capped job that passes, an engineering owner or a re-run that is held, or a roster read from the pull request's head, a run that starts without room before its longest wait, a pull-request run that starts while `main` waits, a job admission could skip, or a peak below the jobs its run holds fails |
+| 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 |
+| 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 |
+| FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver | 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 | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a `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 fails |
## Decision log
@@ -650,6 +658,46 @@ Rejected: larger runners for these lanes (measured no faster than the standard
four-core runners); keeping four unit legs, whose slowest leg took about eight
minutes.
+### DEC-16 — CI holds itself to about ninety jobs, and main fits first
+
+**Reference:** `spec:AST-030/DEC-16`
+**Decider:** `cixzhang`, `2026-10-31`
+
+GitHub offers no repository-wide limit on concurrent jobs: a `concurrency` group
+serializes runs and does not count jobs. So every run of the CI and Main
+workflows waits at its start until the other active runs' estimated jobs plus
+its own fit under ninety. Small workflows that are not admitted (linting, review
+bookkeeping, report publishing) always count at least the most they were
+measured running at once, eighteen jobs, so the room they can take stays free.
+Each CI or Main run counts its live jobs: a pull-request run still waiting
+counts only the job that waits, so waiting runs hold each other back by no more
+than they use, and a run admitted in the last three minutes counts at least its
+planned most. A look reads the active runs and each CI or Main run's jobs once,
+so it costs two run listings plus one call per active CI or Main run. A pull
+request looks at most twice, and a run starts rather than spend a low API
+budget. A `main` full check, release re-check or baseline capture (every
+dispatch of the CI workflow) goes first: while one waits, pull-request runs wait
+too. Every job ends within its fifteen-minute budget, so `main` fits within
+fifteen minutes. Nothing is reserved for `main` outside those minutes.
+
+CI can still pass ninety in three rare, bounded ways:
+
+- A run that has waited its longest (fifteen minutes for `main`, twelve for a
+ pull request) starts whatever the load, even while a `main` check waits. That
+ happens when a job outlives its budget, such as the thirty-minute macOS Swift
+ job, and the run is over by at most its own jobs until that job ends.
+- Runs that look within the same few seconds can each see room. A random
+ 0–20 s on every later look spreads them, and the excess is at most one run's
+ jobs until its next look.
+- A run starts when the GitHub API cannot be read, a rate limit included. It is
+ over by at most its own jobs.
+
+Rejected: a fixed reserve for `main` (it left about half the ceiling idle and
+stalled the pull-request queue); starting `main`'s checks at once (a burst would
+pass ninety); a check in every job (it spent the shared API budget); admitting
+the small workflows too (one or two slim jobs a run do not repay two API calls
+each).
+
## Open questions
None.