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.ymlnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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 indiff --git a/.github/scripts/shadcn-registry-ci.test.mjs b/.github/scripts/shadcn-registry-ci.test.mjsindex 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.mjsindex 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.mjsindex 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.ymlindex 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-slimsteps:@@ -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-slimpermissions:@@ -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-armtimeout-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-latesttimeout-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-slimtimeout-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-slimtimeout-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-armtimeout-minutes: 15diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.ymlindex 5ff9cd6036..6d511abf16 100644--- a/.github/workflows/deploy.yml+++ b/.github/workflows/deploy.yml@@ -43,6 +43,8 @@ jobs:main-commit:runs-on: ubuntu-slimpermissions:+ # actions: read lets the admission step count CI's live jobs.+ actions: readcontents: readoutputs: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.mdindex 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 Buildpackage's browser and fixture-contrast contracts) run only when the pullrequest 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 vouchfor it.** A draft pull request runs no CI, and marking it ready for reviewstarts 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`, acommit in `main`'s history that has the size records the build lane keeps, andevery 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 runningvalidation, 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 standardfour-core runners); keeping four unit legs, whose slowest leg took about eightminutes.+### 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 questionsNone.