An open source design system that's fully customizable and agent ready
TypeScript
Add trusted visual acceptance recovery dispatch (#5600)
Cindy Zhange6507a95fb13
diff --git a/.github/scripts/visual-gate/lib/baseline-publication-lock.mjs b/.github/scripts/visual-gate/lib/baseline-publication-lock.mjsnew file mode 100644index 0000000000..ca2c19ca12--- /dev/null+++ b/.github/scripts/visual-gate/lib/baseline-publication-lock.mjs@@ -0,0 +1,429 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++// Durable FIFO publication lock shared by automatic acceptance promotion and+// manual baseline promotion. GitHub Actions concurrency is not used here:+// even with cancel-in-progress:false it keeps only one pending run and cancels+// an older pending publisher when a third arrives.++import {spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';++const QUEUE_REL = path.join('visual-gate', 'publication-queue');+const HOLDER_NAME = 'holder.json';+const RUN_ID = /^[1-9][0-9]*$/;++function refuse(message) {+ throw new Error(`baseline publication lock refused: ${message}`);+}++function run(command, args, options = {}) {+ const result = spawnSync(command, args, {+ encoding: 'utf8',+ ...options,+ });+ if (result.status !== 0) {+ refuse(+ `${command} ${args[0] ?? ''} failed: ${+ result.stderr?.trim() ||+ result.stdout?.trim() ||+ `exit ${result.status}`+ }`,+ );+ }+ return result.stdout.trim();+}++function git(cwd, ...args) {+ return run('git', ['-C', cwd, ...args]);+}++function sleep(ms) {+ return new Promise(resolve => setTimeout(resolve, ms));+}++function validateIdentity(repository, runId) {+ if (typeof repository !== 'string' || !/^[^/]+\/[^/]+$/.test(repository)) {+ refuse('repository identity is invalid');+ }+ if (!Number.isSafeInteger(runId) || runId <= 0) {+ refuse('current run id is invalid');+ }+}++function validTicket(value, repository, runId) {+ return (+ Number.isSafeInteger(runId) &&+ runId > 0 &&+ value?.version === 1 &&+ value.repository === repository &&+ value.runId === runId+ );+}++export function orderedTickets(entries, repository) {+ if (!Array.isArray(entries)) refuse('queue entries are invalid');+ const tickets = [];+ const seen = new Set();+ for (const entry of entries) {+ if (!RUN_ID.test(entry?.name ?? '')) continue;+ const runId = Number(entry.name);+ if (!validTicket(entry.value, repository, runId)) {+ refuse(`queue ticket ${entry.name} has invalid identity`);+ }+ if (seen.has(runId)) refuse('queue repeats a run id');+ seen.add(runId);+ tickets.push(entry.value);+ }+ return tickets.sort((a, b) => a.runId - b.runId);+}++export function publicationBlockers(entries, repository, currentRunId) {+ validateIdentity(repository, currentRunId);+ const tickets = orderedTickets(entries, repository);+ if (!tickets.some(ticket => ticket.runId === currentRunId)) {+ refuse(`queue ticket for run ${currentRunId} is missing`);+ }+ return tickets.filter(ticket => ticket.runId < currentRunId);+}++export function isTerminalRun(status) {+ return status === 'completed' || status === 'missing';+}++function readJSON(file) {+ try {+ return JSON.parse(fs.readFileSync(file, 'utf8'));+ } catch {+ return null;+ }+}++function queueState(checkout, repository) {+ const root = path.join(checkout, QUEUE_REL);+ if (!fs.existsSync(root)) return {entries: [], invalid: [], holder: null};+ const entries = [];+ const invalid = [];+ let holder = null;+ for (const entry of fs.readdirSync(root, {withFileTypes: true})) {+ if (!entry.isFile() || !entry.name.endsWith('.json')) continue;+ const value = readJSON(path.join(root, entry.name));+ if (entry.name === HOLDER_NAME) {+ if (!validTicket(value, repository, value?.runId)) {+ refuse('publication holder has invalid identity');+ }+ holder = value;+ continue;+ }+ const name = entry.name.slice(0, -'.json'.length);+ if (!RUN_ID.test(name)) {+ invalid.push(entry.name);+ continue;+ }+ const runId = Number(name);+ if (!validTicket(value, repository, runId)) {+ invalid.push(entry.name);+ continue;+ }+ entries.push({name, value});+ }+ return {entries, invalid, holder};+}++function checkoutPages({repository, token, tempRoot}) {+ const checkout = fs.mkdtempSync(path.join(tempRoot, 'baseline-queue-'));+ const url =+ process.env.ASTRYX_BASELINE_QUEUE_URL ??+ `https://x-access-token:${token}@github.com/${repository}.git`;+ run('git', [+ 'clone',+ '--quiet',+ '--depth=1',+ '--filter=blob:none',+ '--sparse',+ '--single-branch',+ '--branch',+ 'gh-pages',+ url,+ checkout,+ ]);+ git(checkout, 'sparse-checkout', 'set', QUEUE_REL);+ return checkout;+}++async function mutateQueue({repository, token, tempRoot, mutate}) {+ for (let attempt = 1; attempt <= 10; attempt += 1) {+ const checkout = checkoutPages({repository, token, tempRoot});+ try {+ const mutation = mutate(checkout);+ if (!mutation.changed) return mutation.value;+ git(checkout, 'config', 'user.name', 'github-actions[bot]');+ git(+ checkout,+ 'config',+ 'user.email',+ 'github-actions[bot]@users.noreply.github.com',+ );+ git(checkout, 'add', '-A', QUEUE_REL);+ git(+ checkout,+ 'commit',+ '-qm',+ 'visual baseline: update publication queue',+ );+ const pushed = spawnSync(+ 'git',+ ['-C', checkout, 'push', 'origin', 'gh-pages'],+ {+ encoding: 'utf8',+ },+ );+ if (pushed.status === 0) return mutation.value;+ } finally {+ fs.rmSync(checkout, {recursive: true, force: true});+ }+ await sleep(attempt * 1000);+ }+ refuse('could not update the publication queue after 10 attempts');+}++function ticketValue(repository, runId) {+ return {version: 1, repository, runId};+}++async function enqueue({repository, runId, token, tempRoot}) {+ await mutateQueue({+ repository,+ token,+ tempRoot,+ mutate(checkout) {+ const file = path.join(checkout, QUEUE_REL, `${runId}.json`);+ if (fs.existsSync(file)) {+ if (!validTicket(readJSON(file), repository, runId)) {+ refuse('existing queue ticket has invalid identity');+ }+ return {changed: false};+ }+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(+ file,+ `${JSON.stringify(ticketValue(repository, runId), null, 2)}\n`,+ );+ return {changed: true};+ },+ });+ process.stdout.write(`Queued baseline publication run ${runId}.\n`);+}++async function release({repository, runId, token, tempRoot}) {+ await mutateQueue({+ repository,+ token,+ tempRoot,+ mutate(checkout) {+ const root = path.join(checkout, QUEUE_REL);+ const ticket = path.join(root, `${runId}.json`);+ const holder = path.join(root, HOLDER_NAME);+ let changed = false;+ if (fs.existsSync(ticket)) {+ fs.rmSync(ticket);+ changed = true;+ }+ const held = readJSON(holder);+ if (held?.runId === runId) {+ fs.rmSync(holder);+ changed = true;+ }+ return {changed};+ },+ });+ process.stdout.write(`Released baseline publication run ${runId}.\n`);+}++async function removeInvalid({repository, names, token, tempRoot}) {+ await mutateQueue({+ repository,+ token,+ tempRoot,+ mutate(checkout) {+ let changed = false;+ for (const name of names) {+ const file = path.join(checkout, QUEUE_REL, name);+ if (fs.existsSync(file)) {+ fs.rmSync(file);+ changed = true;+ }+ }+ return {changed};+ },+ });+}++async function claim({repository, runId, token, tempRoot}) {+ return mutateQueue({+ repository,+ token,+ tempRoot,+ mutate(checkout) {+ const state = queueState(checkout, repository);+ if (state.invalid.length > 0) return {changed: false, value: false};+ if (state.holder) {+ return {changed: false, value: state.holder.runId === runId};+ }+ const tickets = orderedTickets(state.entries, repository);+ if (tickets[0]?.runId !== runId) return {changed: false, value: false};+ const holder = path.join(checkout, QUEUE_REL, HOLDER_NAME);+ fs.writeFileSync(+ holder,+ `${JSON.stringify(ticketValue(repository, runId), null, 2)}\n`,+ );+ return {changed: true, value: true};+ },+ });+}++function runStatus(repository, runId) {+ const result = spawnSync(+ 'gh',+ ['api', `repos/${repository}/actions/runs/${runId}`],+ {encoding: 'utf8'},+ );+ if (result.status === 0) {+ try {+ return JSON.parse(result.stdout).status;+ } catch (error) {+ refuse(`cannot parse queued run ${runId}: ${error.message}`);+ }+ }+ if (/HTTP 404|Not Found/i.test(result.stderr ?? '')) return 'missing';+ refuse(+ `cannot resolve queued run ${runId}: ${+ result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status}`+ }`,+ );+}++async function waitForTurn({+ repository,+ runId,+ token,+ tempRoot,+ timeoutMs = 75 * 60 * 1000,+}) {+ const started = Date.now();+ const checkTimeout = blocker => {+ if (Date.now() - started >= timeoutMs) {+ refuse(+ `timed out behind baseline publication run ${blocker ?? 'unknown'}`,+ );+ }+ };+ while (true) {+ const checkout = checkoutPages({repository, token, tempRoot});+ let state;+ try {+ state = queueState(checkout, repository);+ } finally {+ fs.rmSync(checkout, {recursive: true, force: true});+ }+ if (state.invalid.length > 0) {+ checkTimeout(state.holder?.runId);+ await removeInvalid({+ repository,+ names: state.invalid,+ token,+ tempRoot,+ });+ continue;+ }+ if (state.holder?.runId === runId) {+ process.stdout.write(+ `Baseline publication turn acquired by run ${runId}.\n`,+ );+ return;+ }+ if (state.holder) {+ if (isTerminalRun(runStatus(repository, state.holder.runId))) {+ checkTimeout(state.holder.runId);+ await release({+ repository,+ runId: state.holder.runId,+ token,+ tempRoot,+ });+ continue;+ }+ } else {+ const blockers = publicationBlockers(state.entries, repository, runId);+ let pruned = false;+ for (const blocker of blockers) {+ if (isTerminalRun(runStatus(repository, blocker.runId))) {+ checkTimeout(blocker.runId);+ await release({+ repository,+ runId: blocker.runId,+ token,+ tempRoot,+ });+ pruned = true;+ }+ }+ if (pruned) continue;+ if (+ blockers.length === 0 &&+ (await claim({repository, runId, token, tempRoot}))+ ) {+ process.stdout.write(+ `Baseline publication turn acquired by run ${runId}.\n`,+ );+ return;+ }+ }+ const blocker =+ state.holder?.runId ??+ orderedTickets(state.entries, repository)[0]?.runId;+ checkTimeout(blocker);+ process.stdout.write(`Waiting for baseline publication run ${blocker}.\n`);+ await sleep(30000);+ }+}++if (+ process.argv[1] &&+ fs.realpathSync(process.argv[1]) ===+ fs.realpathSync(fileURLToPath(import.meta.url))+) {+ const command = process.argv[2];+ const repository = process.env.GITHUB_REPOSITORY ?? '';+ const runId = Number(process.env.GITHUB_RUN_ID);+ const token = process.env.GH_TOKEN ?? '';+ const tempRoot = process.env.RUNNER_TEMP || os.tmpdir();+ try {+ validateIdentity(repository, runId);+ if (!token) refuse('GitHub token is missing');+ if (command === 'enqueue') {+ await enqueue({repository, runId, token, tempRoot});+ } else if (command === 'wait') {+ const configuredTimeout = process.env.ASTRYX_BASELINE_LOCK_TIMEOUT_MS;+ const timeoutMs =+ configuredTimeout === undefined ? undefined : Number(configuredTimeout);+ if (+ timeoutMs !== undefined &&+ (!Number.isFinite(timeoutMs) || timeoutMs < 0)+ ) {+ refuse('lock timeout is invalid');+ }+ await waitForTurn({repository, runId, token, tempRoot, timeoutMs});+ } else if (command === 'release') {+ await release({repository, runId, token, tempRoot});+ } else {+ refuse('usage: baseline-publication-lock.mjs <enqueue|wait|release>');+ }+ } catch (error) {+ console.error(error.message);+ process.exitCode = 1;+ }+}diff --git a/.github/scripts/visual-gate/lib/baseline-publication-lock.test.mjs b/.github/scripts/visual-gate/lib/baseline-publication-lock.test.mjsnew file mode 100644index 0000000000..1f66f739a7--- /dev/null+++ b/.github/scripts/visual-gate/lib/baseline-publication-lock.test.mjs@@ -0,0 +1,254 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {execFileSync, spawnSync} from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';++import {afterEach, describe, expect, it} from 'vitest';++import {+ isTerminalRun,+ orderedTickets,+ publicationBlockers,+} from './baseline-publication-lock.mjs';++const REPO = 'facebook/astryx';+const SCRIPT = fileURLToPath(+ new URL('./baseline-publication-lock.mjs', import.meta.url),+);+const roots = [];++afterEach(() => {+ for (const root of roots.splice(0)) {+ fs.rmSync(root, {recursive: true, force: true});+ }+});++function ticket(runId, workflow) {+ return {+ name: String(runId),+ value: {version: 1, repository: REPO, runId, workflow},+ };+}++function harness() {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'baseline-lock-'));+ roots.push(root);+ const seed = path.join(root, 'seed');+ const remote = path.join(root, 'remote.git');+ const bin = path.join(root, 'bin');+ fs.mkdirSync(seed);+ fs.mkdirSync(bin);+ execFileSync('git', ['init', '-q', '-b', 'gh-pages'], {cwd: seed});+ execFileSync('git', ['config', 'user.name', 'Test'], {cwd: seed});+ execFileSync('git', ['config', 'user.email', '[email protected]'], {+ cwd: seed,+ });+ fs.writeFileSync(path.join(seed, '.nojekyll'), '');+ execFileSync('git', ['add', '.'], {cwd: seed});+ execFileSync('git', ['commit', '-qm', 'seed'], {cwd: seed});+ execFileSync('git', ['clone', '-q', '--bare', seed, remote], {cwd: root});+ const gh = path.join(bin, 'gh');+ fs.writeFileSync(gh, '#!/bin/sh\nprintf \'{"status":"in_progress"}\\n\'\n');+ fs.chmodSync(gh, 0o755);++ const invoke = (command, runId, extra = {}) =>+ spawnSync(process.execPath, [SCRIPT, command], {+ encoding: 'utf8',+ env: {+ ...process.env,+ PATH: `${bin}:${process.env.PATH}`,+ ASTRYX_BASELINE_QUEUE_URL: `file://${remote}`,+ GH_TOKEN: 'test-token',+ GITHUB_REPOSITORY: REPO,+ GITHUB_RUN_ID: String(runId),+ RUNNER_TEMP: root,+ ...extra,+ },+ });+ return {root, remote, gh, invoke};+}++describe('baseline publication lock', () => {+ it('orders normal, recovery, and manual requests in immutable run order', () => {+ expect(+ orderedTickets(+ [ticket(103, 'recovery'), ticket(99, 'manual'), ticket(101, 'normal')],+ REPO,+ ).map(value => value.runId),+ ).toEqual([99, 101, 103]);+ });++ it('keeps every older accepted publication ahead of a newer request', () => {+ expect(+ publicationBlockers(+ [ticket(200, 'normal'), ticket(201, 'recovery'), ticket(202, 'manual')],+ REPO,+ 202,+ ).map(value => value.runId),+ ).toEqual([200, 201]);+ });++ it('never lets a newer recovery or manual request block older accepted work', () => {+ expect(+ publicationBlockers(+ [ticket(200, 'normal'), ticket(201, 'recovery'), ticket(202, 'manual')],+ REPO,+ 200,+ ),+ ).toEqual([]);+ });++ it('prunes completed or missing abandoned runs, but never active ones', () => {+ expect(isTerminalRun('completed')).toBe(true);+ expect(isTerminalRun('missing')).toBe(true);+ for (const status of [+ 'requested',+ 'queued',+ 'pending',+ 'waiting',+ 'in_progress',+ ]) {+ expect(isTerminalRun(status)).toBe(false);+ }+ });++ it('queues two real runs without cancelling or overtaking the older one', () => {+ const {root, remote, invoke} = harness();+ expect(invoke('enqueue', 200).status).toBe(0);+ expect(invoke('enqueue', 201).status).toBe(0);+ const blocked = invoke('wait', 201, {+ ASTRYX_BASELINE_LOCK_TIMEOUT_MS: '0',+ });+ expect(blocked.status).not.toBe(0);+ expect(blocked.stderr).toMatch(+ /timed out behind baseline publication run 200/,+ );+ expect(invoke('wait', 200).status).toBe(0);+ expect(invoke('release', 200).status).toBe(0);+ expect(invoke('wait', 201).status).toBe(0);+ expect(invoke('release', 201).status).toBe(0);++ const final = path.join(root, 'final');+ execFileSync('git', ['clone', '-q', '--branch', 'gh-pages', remote, final]);+ const queue = path.join(final, 'visual-gate', 'publication-queue');+ expect(fs.existsSync(queue) ? fs.readdirSync(queue) : []).toEqual([]);+ });++ it('keeps mutual exclusion when a lower-id run enqueues after the holder', () => {+ const {invoke} = harness();+ expect(invoke('enqueue', 201).status).toBe(0);+ expect(invoke('wait', 201).status).toBe(0);+ expect(invoke('enqueue', 200).status).toBe(0);+ const lateOlder = invoke('wait', 200, {+ ASTRYX_BASELINE_LOCK_TIMEOUT_MS: '0',+ });+ expect(lateOlder.status).not.toBe(0);+ expect(lateOlder.stderr).toMatch(+ /timed out behind baseline publication run 201/,+ );+ expect(invoke('release', 201).status).toBe(0);+ expect(invoke('wait', 200).status).toBe(0);+ expect(invoke('release', 200).status).toBe(0);+ });++ it('fails closed instead of deleting a corrupt active holder', () => {+ const {root, remote, invoke} = harness();+ expect(invoke('enqueue', 301).status).toBe(0);+ expect(invoke('wait', 301).status).toBe(0);++ const writer = path.join(root, 'holder-writer');+ execFileSync('git', [+ 'clone',+ '-q',+ '--branch',+ 'gh-pages',+ remote,+ writer,+ ]);+ execFileSync('git', ['config', 'user.name', 'Test'], {cwd: writer});+ execFileSync('git', ['config', 'user.email', '[email protected]'], {+ cwd: writer,+ });+ fs.writeFileSync(+ path.join(writer, 'visual-gate', 'publication-queue', 'holder.json'),+ `${JSON.stringify({+ version: 1,+ repository: REPO,+ runId: '301',+ })}\n`,+ );+ execFileSync('git', ['add', '.'], {cwd: writer});+ execFileSync('git', ['commit', '-qm', 'corrupt holder'], {cwd: writer});+ execFileSync('git', ['push', '-q', 'origin', 'gh-pages'], {cwd: writer});++ expect(invoke('enqueue', 300).status).toBe(0);+ const result = invoke('wait', 300, {+ ASTRYX_BASELINE_LOCK_TIMEOUT_MS: '0',+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr).toMatch(/publication holder has invalid identity/);+ });++ it('self-heals a missing-run ticket instead of bricking later publication', () => {+ const {gh, invoke} = harness();+ expect(invoke('enqueue', 200).status).toBe(0);+ expect(invoke('enqueue', 201).status).toBe(0);+ fs.writeFileSync(+ gh,+ "#!/bin/sh\necho 'gh: Not Found (HTTP 404)' >&2\nexit 1\n",+ );+ fs.chmodSync(gh, 0o755);+ expect(invoke('wait', 201).status).toBe(0);+ expect(invoke('release', 201).status).toBe(0);+ });++ it('removes a stray JSON file instead of treating it as a lock', () => {+ const {root, remote, invoke} = harness();+ const writer = path.join(root, 'stray-writer');+ execFileSync('git', [+ 'clone',+ '-q',+ '--branch',+ 'gh-pages',+ remote,+ writer,+ ]);+ execFileSync('git', ['config', 'user.name', 'Test'], {cwd: writer});+ execFileSync('git', ['config', 'user.email', '[email protected]'], {+ cwd: writer,+ });+ const queue = path.join(writer, 'visual-gate', 'publication-queue');+ fs.mkdirSync(queue, {recursive: true});+ fs.writeFileSync(path.join(queue, 'stray.json'), '{}\n');+ execFileSync('git', ['add', '.'], {cwd: writer});+ execFileSync('git', ['commit', '-qm', 'stray'], {cwd: writer});+ execFileSync('git', ['push', '-q', 'origin', 'gh-pages'], {cwd: writer});++ expect(invoke('enqueue', 200).status).toBe(0);+ expect(invoke('wait', 200).status).toBe(0);+ expect(invoke('release', 200).status).toBe(0);+ });++ it('ignores stray names and fails closed for a missing or cross-repository ticket', () => {+ expect(() => publicationBlockers([], REPO, 200)).toThrow(+ /queue ticket for run 200 is missing/,+ );+ expect(+ orderedTickets([{name: '../200', value: {untrusted: true}}], REPO),+ ).toEqual([]);+ expect(() =>+ orderedTickets(+ [+ {+ name: '200',+ value: {version: 1, repository: 'fork/astryx', runId: 200},+ },+ ],+ REPO,+ ),+ ).toThrow(/invalid identity/);+ });+});diff --git a/.github/scripts/visual-gate/lib/promotion-identity.mjs b/.github/scripts/visual-gate/lib/promotion-identity.mjsnew file mode 100644index 0000000000..9b1a0b6095--- /dev/null+++ b/.github/scripts/visual-gate/lib/promotion-identity.mjs@@ -0,0 +1,430 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {execFileSync} from 'node:child_process';+import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';++const SHA = /^[0-9a-f]{40}$/;+const REPO = 'facebook/astryx';++const FAILURE_DESCRIPTIONS = {+ 'actions-response-invalid':+ 'Recovery refused: the CI run response was invalid.',+ 'invalid-head': 'Recovery refused: the resolved PR head was invalid.',+ 'invalid-merge': 'Recovery refused: the resolved merge commit was invalid.',+ 'invalid-pr': 'Recovery refused: the PR number was invalid.',+ 'latest-ci-mismatch':+ 'Recovery refused: acceptance is not from the latest completed CI attempt.',+ 'active-ci-retry':+ 'Visual promotion deferred: a newer CI retry is still active.',+ 'merge-not-main':+ 'Recovery refused: the merge commit is not reachable from main.',+ 'pointer-invalid':+ 'Recovery refused: the current acceptance pointer was invalid.',+ 'pointer-missing':+ 'Recovery refused: the current acceptance pointer was missing.',+ 'pr-not-main': 'Recovery refused: the PR was not merged into main.',+ 'pr-not-merged': 'Recovery refused: the PR is not merged.',+ 'record-identity-mismatch':+ 'Recovery refused: the acceptance record identity did not match.',+ 'record-missing':+ 'Recovery refused: the immutable acceptance record was missing.',+ superseded:+ 'Recovery refused: a newer acceptance superseded the reviewed record.',+ 'wrong-pr-response':+ 'Recovery refused: GitHub returned the wrong PR identity.',+};++function refuse(code, message) {+ const error = new Error(`visual promotion refused: ${message}`);+ error.code = code;+ throw error;+}++export function promotionFailure(error) {+ const code =+ typeof error?.code === 'string' && FAILURE_DESCRIPTIONS[error.code]+ ? error.code+ : 'infrastructure-failure';+ return {+ code,+ description:+ FAILURE_DESCRIPTIONS[code] ??+ 'Visual promotion validation failed before publication.',+ };+}++export function recoveryComplete({+ publicationConfirmed,+ gateOutcome,+ releaseOutcome,+}) {+ return (+ publicationConfirmed === true &&+ gateOutcome === 'success' &&+ releaseOutcome === 'success'+ );+}++export function recoveryOperationResult({+ jobResult,+ recoveryComplete: complete,+ mutationDeferred = false,+ failureDescription = null,+}) {+ if (+ jobResult === 'failure' ||+ jobResult === 'cancelled' ||+ Boolean(failureDescription)+ ) {+ return 'failure';+ }+ if (jobResult === 'success' && complete === true) return 'success';+ if (mutationDeferred === true && jobResult === 'success') {+ return 'deferred';+ }+ return 'failure';+}++export function promotionStatusProjection({+ headKnown,+ validationOk,+ acceptanceFound,+ promotionResult,+ mutationDeferred = false,+ deferredDescription = null,+ failureDescription,+}) {+ if (!headKnown) return null;+ if (validationOk && !acceptanceFound) return null;+ // Terminal trusted-operation outcomes always outrank deferral. A late retry+ // must never turn a failed/cancelled publisher into a pending status.+ if (promotionResult === 'failure' || promotionResult === 'cancelled') {+ return {+ state: 'failure',+ description:+ String(failureDescription ?? '').slice(0, 140) ||+ 'Visual promotion failed; inspect the linked workflow run.',+ };+ }+ if (validationOk && acceptanceFound && promotionResult === 'success') {+ return {+ state: 'success',+ description: 'Accepted pixels promoted to the visual baseline.',+ };+ }+ if (+ validationOk &&+ acceptanceFound &&+ mutationDeferred &&+ promotionResult === 'deferred' &&+ !failureDescription+ ) {+ return {+ state: 'pending',+ description:+ String(deferredDescription ?? '').slice(0, 140) ||+ FAILURE_DESCRIPTIONS['active-ci-retry'],+ };+ }+ return {+ state: 'failure',+ description:+ String(failureDescription ?? '').slice(0, 140) ||+ 'Visual promotion failed; inspect the linked workflow run.',+ };+}++function readJSON(file) {+ try {+ return JSON.parse(fs.readFileSync(file, 'utf8'));+ } catch (error) {+ refuse('infrastructure-failure', `cannot read ${file}: ${error.message}`);+ }+}++export function resolvePullRequestIdentity({+ pull,+ requestedPr,+ repository = REPO,+ baseRef = 'main',+ compareStatus,+}) {+ const pr = Number(requestedPr);+ if (!Number.isSafeInteger(pr) || pr <= 0)+ refuse('invalid-pr', 'invalid PR number');+ if (pull?.number !== pr)+ refuse('wrong-pr-response', `GitHub returned the wrong PR for #${pr}`);+ if (pull.state !== 'closed' || pull.merged !== true || !pull.merged_at) {+ refuse('pr-not-merged', `PR #${pr} is not merged`);+ }+ if (pull.base?.ref !== baseRef || pull.base?.repo?.full_name !== repository) {+ refuse(+ 'pr-not-main',+ `PR #${pr} was not merged into ${repository}:${baseRef}`,+ );+ }+ if (!SHA.test(pull.head?.sha ?? ''))+ refuse('invalid-head', 'resolved head SHA is invalid');+ if (!SHA.test(pull.merge_commit_sha ?? '')) {+ refuse('invalid-merge', 'resolved merge SHA is invalid');+ }+ if (!['ahead', 'identical'].includes(compareStatus)) {+ refuse(+ 'merge-not-main',+ `merge ${pull.merge_commit_sha} is not reachable from ${baseRef}`,+ );+ }+ return {+ pr,+ headSha: pull.head.sha,+ mergeSha: pull.merge_commit_sha,+ };+}++export function resolveAcceptanceIdentity({+ pages,+ pr,+ head,+ missingOk = false,+ expectedRecordRel = null,+ repository = REPO,+}) {+ if (!Number.isSafeInteger(pr) || pr <= 0 || !SHA.test(head)) {+ refuse('invalid-head', 'invalid PR/head');+ }+ const root = path.join(pages, 'visual-gate', 'acceptances', String(pr), head);+ const pointerFile = path.join(root, 'current.json');+ if (!fs.existsSync(pointerFile)) {+ if (missingOk) return {found: false};+ refuse('pointer-missing', 'current visual acceptance pointer is missing');+ }+ const pointer = readJSON(pointerFile);+ const expectedRel = `${pointer?.run}/${pointer?.attempt}/acceptance.json`;+ if (+ pointer?.version !== 1 ||+ !Number.isSafeInteger(pointer.run) ||+ pointer.run <= 0 ||+ !Number.isSafeInteger(pointer.attempt) ||+ pointer.attempt <= 0 ||+ pointer.record !== expectedRel+ ) {+ refuse('pointer-invalid', 'current visual acceptance pointer is invalid');+ }+ if (expectedRecordRel && pointer.record !== expectedRecordRel) {+ refuse(+ 'superseded',+ 'a newer visual acceptance superseded the reviewed record',+ );+ }+ const recordPath = path.join(root, pointer.record);+ if (!fs.existsSync(recordPath))+ refuse('record-missing', 'visual acceptance record is missing');+ const record = readJSON(recordPath);+ if (+ record?.repo !== repository ||+ record.pr !== pr ||+ record.headSha !== head ||+ record.run?.id !== pointer.run ||+ record.run?.attempt !== pointer.attempt+ ) {+ refuse(+ 'record-identity-mismatch',+ 'visual acceptance record identity does not match this merged head',+ );+ }+ return {+ found: true,+ recordPath,+ recordRel: pointer.record,+ runId: pointer.run,+ runAttempt: pointer.attempt,+ };+}++export function resolveCIState(workflowRuns, accepted) {+ if (!Array.isArray(workflowRuns)) {+ refuse('actions-response-invalid', 'GitHub Actions response is invalid');+ }+ const identity = run => {+ if (+ run?.name !== 'CI' ||+ !Number.isSafeInteger(run.id) ||+ run.id <= 0 ||+ !Number.isSafeInteger(run.run_attempt) ||+ run.run_attempt <= 0+ ) {+ return null;+ }+ return {+ id: run.id,+ attempt: run.run_attempt,+ status: run.status,+ conclusion: run.conclusion ?? null,+ };+ };+ const compare = (first, second) =>+ first.id - second.id || first.attempt - second.attempt;+ const ci = workflowRuns.map(identity).filter(Boolean);+ // A cancelled retry produces no new evidence. The last non-cancelled terminal+ // attempt remains the completed identity until another attempt completes.+ const latestCompleted = ci+ .filter(run => run.status === 'completed' && run.conclusion !== 'cancelled')+ .sort(compare)+ .at(-1);+ if (+ !latestCompleted ||+ latestCompleted.id !== accepted.runId ||+ latestCompleted.attempt !== accepted.runAttempt+ ) {+ refuse(+ 'latest-ci-mismatch',+ 'accepted evidence is not from the latest completed CI attempt',+ );+ }+ const newerActive = ci+ .filter(+ run => run.status !== 'completed' && compare(run, latestCompleted) > 0,+ )+ .sort(compare)+ .at(-1);+ return {+ latestCompleted: {+ id: latestCompleted.id,+ attempt: latestCompleted.attempt,+ },+ newerActive: newerActive+ ? {+ id: newerActive.id,+ attempt: newerActive.attempt,+ status: newerActive.status,+ }+ : null,+ };+}++export function assertLatestCompletedCI(workflowRuns, accepted) {+ return resolveCIState(workflowRuns, accepted);+}++function flag(args, name) {+ const index = args.indexOf(`--${name}`);+ return index === -1 ? null : args[index + 1];+}++function githubJSON(endpoint) {+ return JSON.parse(execFileSync('gh', ['api', endpoint], {encoding: 'utf8'}));+}++export function expandCIHistory(workflowRuns, loadAttempt) {+ if (!Array.isArray(workflowRuns)) {+ refuse('actions-response-invalid', 'GitHub Actions response is invalid');+ }+ const byRun = new Map();+ for (const run of workflowRuns) {+ if (+ run?.name !== 'CI' ||+ !Number.isSafeInteger(run.id) ||+ !Number.isSafeInteger(run.run_attempt)+ ) {+ continue;+ }+ const prior = byRun.get(run.id);+ if (!prior || run.run_attempt > prior.run_attempt) byRun.set(run.id, run);+ }+ const currentRuns = [...byRun.values()].sort((a, b) => b.id - a.id);+ const history = [];+ let foundCompleted = false;+ for (const current of currentRuns) {+ history.push(current);+ if (current.status === 'completed' && current.conclusion !== 'cancelled') {+ break;+ }+ for (let attempt = current.run_attempt - 1; attempt >= 1; attempt -= 1) {+ const prior = loadAttempt(current.id, attempt);+ history.push(prior);+ if (prior.status === 'completed' && prior.conclusion !== 'cancelled') {+ foundCompleted = true;+ break;+ }+ }+ if (foundCompleted) break;+ }+ return history;+}++function loadCIHistory(head) {+ const response = githubJSON(+ `repos/${REPO}/actions/runs?event=pull_request&head_sha=${head}&per_page=100`,+ );+ return expandCIHistory(response.workflow_runs, (runId, attempt) =>+ githubJSON(`repos/${REPO}/actions/runs/${runId}/attempts/${attempt}`),+ );+}++function resolveFromGitHub(args) {+ const pages = path.resolve(flag(args, 'pages'));+ const pr = Number(flag(args, 'pr'));+ const head = flag(args, 'head') ?? '';+ const missingOkValue = flag(args, 'missing-ok') ?? 'false';+ if (!['true', 'false'].includes(missingOkValue)) {+ refuse('infrastructure-failure', 'missing-ok must be true or false');+ }+ const resolved = resolveAcceptanceIdentity({+ pages,+ pr,+ head,+ missingOk: missingOkValue === 'true',+ expectedRecordRel: flag(args, 'expected-record-rel'),+ });+ if (!resolved.found) return resolved;++ let runs;+ try {+ runs = loadCIHistory(head);+ } catch (error) {+ refuse(+ 'infrastructure-failure',+ `cannot resolve the latest completed CI run: ${error.message}`,+ );+ }+ const ciState = resolveCIState(runs, resolved);+ return {+ ...resolved,+ latestCompleted: ciState.latestCompleted,+ newerActive: ciState.newerActive,+ deferred: ciState.newerActive !== null,+ deferredDescription:+ ciState.newerActive === null+ ? null+ : FAILURE_DESCRIPTIONS['active-ci-retry'],+ };+}++if (+ process.argv[1] &&+ fs.realpathSync(process.argv[1]) ===+ fs.realpathSync(fileURLToPath(import.meta.url))+) {+ try {+ const [command, ...args] = process.argv.slice(2);+ if (command !== 'resolve-acceptance') {+ refuse(+ 'infrastructure-failure',+ 'usage: promotion-identity.mjs resolve-acceptance [flags]',+ );+ }+ process.stdout.write(+ `${JSON.stringify({ok: true, ...resolveFromGitHub(args)})}\n`,+ );+ } catch (error) {+ process.stdout.write(+ `${JSON.stringify({+ ok: false,+ ...promotionFailure(error),+ message: String(error?.message ?? error).slice(0, 500),+ })}\n`,+ );+ }+}diff --git a/.github/scripts/visual-gate/lib/promotion-identity.test.mjs b/.github/scripts/visual-gate/lib/promotion-identity.test.mjsnew file mode 100644index 0000000000..33ac7033fc--- /dev/null+++ b/.github/scripts/visual-gate/lib/promotion-identity.test.mjs@@ -0,0 +1,655 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';++import {afterEach, describe, expect, it} from 'vitest';++import {+ assertLatestCompletedCI,+ expandCIHistory,+ promotionFailure,+ promotionStatusProjection,+ recoveryComplete,+ recoveryOperationResult,+ resolveAcceptanceIdentity,+ resolveCIState,+ resolvePullRequestIdentity,+} from './promotion-identity.mjs';++const HEAD = 'a'.repeat(40);+const MERGE = 'b'.repeat(40);+const RECORD_REL = '123/2/acceptance.json';+const roots = [];++afterEach(() => {+ for (const root of roots.splice(0)) {+ fs.rmSync(root, {recursive: true, force: true});+ }+});++function pull(overrides = {}) {+ const value = {+ number: 42,+ state: 'closed',+ merged: true,+ merged_at: '2026-08-27T07:50:43Z',+ base: {ref: 'main', repo: {full_name: 'facebook/astryx'}},+ head: {sha: HEAD, ref: 'feature', repo: {id: 99}},+ merge_commit_sha: MERGE,+ };+ return {+ ...value,+ ...overrides,+ base: {...value.base, ...overrides.base},+ head: {...value.head, ...overrides.head},+ };+}++function resolvePull(value = pull(), overrides = {}) {+ return resolvePullRequestIdentity({+ pull: value,+ requestedPr: 42,+ repository: 'facebook/astryx',+ baseRef: 'main',+ compareStatus: 'ahead',+ ...overrides,+ });+}++function acceptanceFixture() {+ const pages = fs.mkdtempSync(path.join(os.tmpdir(), 'promotion-identity-'));+ roots.push(pages);+ const root = path.join(pages, 'visual-gate', 'acceptances', '42', HEAD);+ fs.mkdirSync(path.join(root, '123', '2'), {recursive: true});+ fs.writeFileSync(+ path.join(root, 'current.json'),+ `${JSON.stringify({+ version: 1,+ run: 123,+ attempt: 2,+ record: RECORD_REL,+ })}\n`,+ );+ fs.writeFileSync(+ path.join(root, RECORD_REL),+ `${JSON.stringify({+ version: 1,+ repo: 'facebook/astryx',+ pr: 42,+ headSha: HEAD,+ run: {id: 123, attempt: 2},+ })}\n`,+ );+ return {pages, root};+}++describe('promotion PR identity', () => {+ it('returns only server-resolved identity for a merge reachable from main', () => {+ expect(resolvePull()).toEqual({+ pr: 42,+ headSha: HEAD,+ mergeSha: MERGE,+ });+ });++ it('does not depend on a merged PR head branch still existing', () => {+ expect(resolvePull(pull({head: {repo: null, ref: null}}))).toMatchObject({+ pr: 42,+ headSha: HEAD,+ mergeSha: MERGE,+ });+ });++ it.each([+ [+ 'an invalid PR number',+ pull(),+ {requestedPr: 'not-a-number'},+ /invalid PR number/,+ ],+ ['the wrong PR response', pull({number: 43}), {}, /wrong PR/],+ [+ 'an open PR',+ pull({state: 'open', merged: false, merged_at: null}),+ {},+ /not merged/,+ ],+ [+ 'an unmerged closed PR',+ pull({merged: false, merged_at: null}),+ {},+ /not merged/,+ ],+ ['a non-main base', pull({base: {ref: 'release'}}), {}, /not merged into/],+ [+ 'a different base repository',+ pull({base: {repo: {full_name: 'fork/astryx'}}}),+ {},+ /not merged into/,+ ],+ [+ 'an invalid head SHA',+ pull({head: {sha: 'bad'}}),+ {},+ /head SHA is invalid/,+ ],+ [+ 'an invalid merge SHA',+ pull({merge_commit_sha: 'bad'}),+ {},+ /merge SHA is invalid/,+ ],+ [+ 'a merge not in main',+ pull(),+ {compareStatus: 'diverged'},+ /not reachable from main/,+ ],+ ])('fails closed for %s', (_name, value, overrides, error) => {+ expect(() => resolvePull(value, overrides)).toThrow(error);+ });+});++describe('promotion acceptance identity', () => {+ it('binds the current pointer to its immutable record', () => {+ const {pages} = acceptanceFixture();+ expect(+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD}),+ ).toMatchObject({+ found: true,+ recordRel: RECORD_REL,+ runId: 123,+ runAttempt: 2,+ });+ });++ it('allows no acceptance only for normal closed-PR promotion', () => {+ const pages = fs.mkdtempSync(path.join(os.tmpdir(), 'promotion-identity-'));+ roots.push(pages);+ expect(+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD, missingOk: true}),+ ).toEqual({found: false});+ expect(() =>+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD}),+ ).toThrow(/pointer is missing/);+ });++ it('rejects a stale current pointer', () => {+ const {pages} = acceptanceFixture();+ expect(() =>+ resolveAcceptanceIdentity({+ pages,+ pr: 42,+ head: HEAD,+ expectedRecordRel: '124/1/acceptance.json',+ }),+ ).toThrow(/superseded/);+ });++ it('rejects a malformed current pointer', () => {+ const {pages, root} = acceptanceFixture();+ fs.writeFileSync(+ path.join(root, 'current.json'),+ `${JSON.stringify({+ version: 1,+ run: 123,+ attempt: 2,+ record: '../acceptance.json',+ })}\n`,+ );+ expect(() =>+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD}),+ ).toThrow(/pointer is invalid/);+ });++ it('rejects a missing immutable record', () => {+ const {pages, root} = acceptanceFixture();+ fs.rmSync(path.join(root, RECORD_REL));+ expect(() =>+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD}),+ ).toThrow(/record is missing/);+ });++ it.each([+ ['repository', record => (record.repo = 'fork/astryx')],+ ['PR', record => (record.pr = 43)],+ ['head', record => (record.headSha = 'c'.repeat(40))],+ ['run', record => (record.run.id = 124)],+ ['attempt', record => (record.run.attempt = 1)],+ ])('rejects a record %s mismatch', (_name, mutate) => {+ const {pages, root} = acceptanceFixture();+ const file = path.join(root, RECORD_REL);+ const record = JSON.parse(fs.readFileSync(file, 'utf8'));+ mutate(record);+ fs.writeFileSync(file, `${JSON.stringify(record)}\n`);+ expect(() =>+ resolveAcceptanceIdentity({pages, pr: 42, head: HEAD}),+ ).toThrow(/record identity does not match/);+ });++ describe('CI attempt resolution', () => {+ const ci = (id, attempt, status, conclusion = null) => ({+ name: 'CI',+ id,+ run_attempt: attempt,+ status,+ conclusion,+ });++ it('loads prior attempts when the list exposes only active R/3', () => {+ const loaded = [];+ const history = expandCIHistory(+ [ci(123, 3, 'in_progress')],+ (runId, attempt) => {+ loaded.push([runId, attempt]);+ return ci(runId, attempt, 'completed', 'success');+ },+ );+ expect(loaded).toEqual([[123, 2]]);+ expect(resolveCIState(history, {runId: 123, runAttempt: 2})).toEqual({+ latestCompleted: {id: 123, attempt: 2},+ newerActive: {id: 123, attempt: 3, status: 'in_progress'},+ });+ });++ it('keeps completed R/2 eligible while active R/3 defers mutation', () => {+ expect(+ resolveCIState(+ [ci(123, 3, 'in_progress'), ci(123, 2, 'completed', 'success')],+ {runId: 123, runAttempt: 2},+ ),+ ).toEqual({+ latestCompleted: {id: 123, attempt: 2},+ newerActive: {id: 123, attempt: 3, status: 'in_progress'},+ });+ });++ it('supersedes R/2 after R/3 completes', () => {+ expect(() =>+ resolveCIState(+ [+ ci(123, 2, 'completed', 'success'),+ ci(123, 3, 'completed', 'success'),+ ],+ {runId: 123, runAttempt: 2},+ ),+ ).toThrow(/latest completed CI attempt/);+ });++ it('keeps R/2 eligible after R/3 is cancelled', () => {+ expect(+ resolveCIState(+ [+ ci(123, 3, 'completed', 'cancelled'),+ ci(123, 2, 'completed', 'success'),+ ],+ {runId: 123, runAttempt: 2},+ ),+ ).toEqual({+ latestCompleted: {id: 123, attempt: 2},+ newerActive: null,+ });+ });++ it('orders different run ids and attempts independently of API order', () => {+ const runs = [+ ci(125, 1, 'queued'),+ ci(123, 2, 'completed', 'success'),+ ci(124, 1, 'completed', 'cancelled'),+ ci(122, 9, 'completed', 'success'),+ ci(999, 1, 'completed', 'success'),+ ];+ // A non-CI workflow with a larger id must not participate.+ runs.at(-1).name = 'Lint';+ expect(+ resolveCIState(runs.reverse(), {runId: 123, runAttempt: 2}),+ ).toEqual({+ latestCompleted: {id: 123, attempt: 2},+ newerActive: {id: 125, attempt: 1, status: 'queued'},+ });+ });++ it('does not use the first API element as latest completed evidence', () => {+ expect(+ assertLatestCompletedCI(+ [+ ci(120, 1, 'completed', 'success'),+ ci(123, 2, 'completed', 'success'),+ ci(121, 8, 'completed', 'success'),+ ],+ {runId: 123, runAttempt: 2},+ ),+ ).toEqual({+ latestCompleted: {id: 123, attempt: 2},+ newerActive: null,+ });+ });+ });+});++function projectedFailure(run) {+ try {+ run();+ throw new Error('expected resolver refusal');+ } catch (error) {+ const failure = promotionFailure(error);+ return {+ failure,+ projection: promotionStatusProjection({+ headKnown: true,+ validationOk: false,+ acceptanceFound: false,+ promotionResult: 'skipped',+ failureDescription: failure.description,+ }),+ };+ }+}++describe('promotion status projection', () => {+ it.each([+ ['wrong PR response', () => resolvePull(pull({number: 43}))],+ [+ 'open or unmerged PR',+ () => resolvePull(pull({state: 'open', merged: false, merged_at: null})),+ ],+ ['non-main PR', () => resolvePull(pull({base: {ref: 'release'}}))],+ [+ 'merge outside main',+ () => resolvePull(pull(), {compareStatus: 'diverged'}),+ ],+ ])('keeps %s status-silent while the workflow fails', (_name, run) => {+ let failure;+ try {+ run();+ } catch (error) {+ failure = promotionFailure(error);+ }+ expect(failure).toBeDefined();+ expect(+ promotionStatusProjection({+ headKnown: false,+ validationOk: false,+ acceptanceFound: false,+ promotionResult: 'skipped',+ failureDescription: failure.description,+ }),+ ).toBeNull();+ });++ it.each([+ [+ 'missing pointer',+ () => {+ const pages = fs.mkdtempSync(+ path.join(os.tmpdir(), 'promotion-identity-'),+ );+ roots.push(pages);+ return resolveAcceptanceIdentity({pages, pr: 42, head: HEAD});+ },+ ],+ [+ 'stale pointer',+ () => {+ const {pages} = acceptanceFixture();+ return resolveAcceptanceIdentity({+ pages,+ pr: 42,+ head: HEAD,+ expectedRecordRel: '124/1/acceptance.json',+ });+ },+ ],+ [+ 'missing record',+ () => {+ const {pages, root} = acceptanceFixture();+ fs.rmSync(path.join(root, RECORD_REL));+ return resolveAcceptanceIdentity({pages, pr: 42, head: HEAD});+ },+ ],+ [+ 'record mismatch',+ () => {+ const {pages, root} = acceptanceFixture();+ const file = path.join(root, RECORD_REL);+ const record = JSON.parse(fs.readFileSync(file, 'utf8'));+ record.pr = 43;+ fs.writeFileSync(file, `${JSON.stringify(record)}\n`);+ return resolveAcceptanceIdentity({pages, pr: 42, head: HEAD});+ },+ ],+ [+ 'latest CI mismatch',+ () =>+ assertLatestCompletedCI(+ [{name: 'CI', id: 124, run_attempt: 1, status: 'completed'}],+ {runId: 123, runAttempt: 2},+ ),+ ],+ ])('writes a precise failure for %s', (_name, run) => {+ const {failure, projection} = projectedFailure(run);+ expect(failure.code).not.toBe('infrastructure-failure');+ expect(projection).toEqual({+ state: 'failure',+ description: failure.description,+ });+ expect(projection.description.length).toBeLessThanOrEqual(140);+ });++ it.each([+ ['deferred plus lock release failure', 'failure', 'Lock release failed.'],+ ['deferred plus gate dispatch failure', 'failure', 'Gate dispatch failed.'],+ ['deferred plus publication failure', 'failure', 'Publication failed.'],+ ['deferred plus failed job', 'failure', 'Trusted operation failed.'],+ [+ 'deferred plus cancelled job',+ 'cancelled',+ 'Trusted operation cancelled.',+ ],+ ])(+ 'projects %s as failure, never pending',+ (_name, promotionResult, failureDescription) => {+ expect(+ promotionStatusProjection({+ headKnown: true,+ validationOk: true,+ acceptanceFound: true,+ mutationDeferred: true,+ deferredDescription:+ 'Visual promotion deferred: a newer CI retry is still active.',+ promotionResult,+ failureDescription,+ }),+ ).toEqual({state: 'failure', description: failureDescription});+ },+ );++ it('composes a clean successful defer job into pending', () => {+ const promotionResult = recoveryOperationResult({+ jobResult: 'success',+ recoveryComplete: false,+ mutationDeferred: true,+ failureDescription: '',+ });+ expect(promotionResult).toBe('deferred');+ expect(+ promotionStatusProjection({+ headKnown: true,+ validationOk: true,+ acceptanceFound: true,+ mutationDeferred: true,+ deferredDescription:+ 'Visual promotion deferred: a newer CI retry is still active.',+ promotionResult,+ failureDescription: '',+ }),+ ).toEqual({+ state: 'pending',+ description:+ 'Visual promotion deferred: a newer CI retry is still active.',+ });+ });++ it('projects active CI retries as pending only after trusted defer succeeds', () => {+ expect(+ promotionStatusProjection({+ headKnown: true,+ validationOk: true,+ acceptanceFound: true,+ mutationDeferred: true,+ deferredDescription:+ 'Visual promotion deferred: a newer CI retry is still active.',+ promotionResult: 'deferred',+ failureDescription: '',+ }),+ ).toEqual({+ state: 'pending',+ description:+ 'Visual promotion deferred: a newer CI retry is still active.',+ });+ });++ it('treats an unexpected skipped promote job with acceptance as failure', () => {+ expect(+ promotionStatusProjection({+ headKnown: true,+ validationOk: true,+ acceptanceFound: true,+ mutationDeferred: true,+ deferredDescription:+ 'Visual promotion deferred: a newer CI retry is still active.',+ promotionResult: 'skipped',+ failureDescription: '',+ }),+ ).toEqual({+ state: 'failure',+ description: 'Visual promotion failed; inspect the linked workflow run.',+ });+ });++ it('requires the entire trusted operation before returning success', () => {+ const scenarios = [+ {+ name: 'push succeeds but gate dispatch fails',+ publicationConfirmed: true,+ gateOutcome: 'failure',+ releaseOutcome: 'success',+ jobResult: 'failure',+ expected: 'failure',+ },+ {+ name: 'push succeeds but lock release fails',+ publicationConfirmed: true,+ gateOutcome: 'success',+ releaseOutcome: 'failure',+ jobResult: 'failure',+ expected: 'failure',+ },+ {+ name: 'clean deferred operation',+ publicationConfirmed: false,+ gateOutcome: 'skipped',+ releaseOutcome: 'skipped',+ jobResult: 'success',+ mutationDeferred: true,+ expected: 'deferred',+ },+ {+ name: 'unexpected skipped promote job with accepted record',+ publicationConfirmed: false,+ gateOutcome: 'skipped',+ releaseOutcome: 'skipped',+ jobResult: 'skipped',+ mutationDeferred: true,+ expected: 'failure',+ },+ {+ name: 'deferred flag cannot hide an operational failure',+ publicationConfirmed: false,+ gateOutcome: 'failure',+ releaseOutcome: 'success',+ jobResult: 'failure',+ mutationDeferred: true,+ failureDescription: 'Gate dispatch failed.',+ expected: 'failure',+ },+ {+ name: 'push or no-op and finalization succeed',+ publicationConfirmed: true,+ gateOutcome: 'success',+ releaseOutcome: 'success',+ jobResult: 'success',+ expected: 'success',+ },+ {+ name: 'job is cancelled after push',+ publicationConfirmed: true,+ gateOutcome: 'success',+ releaseOutcome: 'success',+ jobResult: 'cancelled',+ expected: 'failure',+ },+ ];+ for (const scenario of scenarios) {+ const complete = recoveryComplete(scenario);+ const operation = recoveryOperationResult({+ jobResult: scenario.jobResult,+ recoveryComplete: complete,+ mutationDeferred: scenario.mutationDeferred ?? false,+ failureDescription: scenario.failureDescription ?? null,+ });+ expect(operation, scenario.name).toBe(scenario.expected);+ }+ });++ it('writes success only after publication succeeds', () => {+ const base = {+ headKnown: true,+ validationOk: true,+ acceptanceFound: true,+ failureDescription: '',+ };+ expect(+ promotionStatusProjection({...base, promotionResult: 'failure'}),+ ).toEqual({+ state: 'failure',+ description: 'Visual promotion failed; inspect the linked workflow run.',+ });+ expect(+ promotionStatusProjection({...base, promotionResult: 'cancelled'}),+ ).toMatchObject({state: 'failure'});+ expect(+ promotionStatusProjection({...base, promotionResult: 'success'}),+ ).toEqual({+ state: 'success',+ description: 'Accepted pixels promoted to the visual baseline.',+ });+ });++ it('preserves normal close behavior when no acceptance exists', () => {+ expect(+ promotionStatusProjection({+ headKnown: true,+ validationOk: true,+ acceptanceFound: false,+ promotionResult: 'skipped',+ failureDescription: '',+ }),+ ).toBeNull();+ });++ it('cannot project a status without a server-resolved head', () => {+ expect(+ promotionStatusProjection({+ headKnown: false,+ validationOk: false,+ acceptanceFound: false,+ promotionResult: 'skipped',+ failureDescription: 'Recovery refused: PR was not found.',+ }),+ ).toBeNull();+ });+});diff --git a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjsindex bc6f117e35..49e891fa19 100644--- a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs+++ b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs@@ -134,7 +134,7 @@ function writeCommandShims(root) {fs.chmodSync(gitShim, 0o755);const ghShim = path.join(bin, 'gh');- fs.writeFileSync(ghShim, '#!/bin/sh\nprintf "%b\\n" "$GH_LATEST"\n');+ fs.writeFileSync(ghShim, '#!/bin/sh\nprintf "%s\\n" "$GH_RUNS_JSON"\n');fs.chmodSync(ghShim, 0o755);const sleepShim = path.join(bin, 'sleep');@@ -259,7 +259,11 @@ function makeFixture(mutate) {return {root, remote, sandbox, bin, after};}-function runPromotion({fixture, latest = '123\\t1\\tcompleted', race = false}) {+function runPromotion({+ fixture,+ latest = {id: 123, run_attempt: 1, status: 'completed'},+ race = false,+}) {const marker = path.join(fixture.root, 'race-injected');const result = spawnSync('/bin/bash',@@ -277,7 +281,10 @@ function runPromotion({fixture, latest = '123\\t1\\tcompleted', race = false}) {MERGE_SHA: MERGE,RECORD_REL,RUNNER_TEMP: path.join(fixture.root, 'runner'),- GH_LATEST: latest,+ GITHUB_OUTPUT: path.join(fixture.root, 'github-output'),+ GH_RUNS_JSON: JSON.stringify({+ workflow_runs: [{name: 'CI', ...latest}],+ }),TEST_INJECT_RACE: race ? '1' : '0',TEST_RACE_MARKER: marker,TEST_REAL_GIT: execFileSync('which', ['git'], {@@ -327,6 +334,40 @@ describe('visual acceptance promotion workflow', () => {});});+ it('is idempotent when the same recovery is dispatched twice', () => {+ const fixture = makeFixture();+ const first = runPromotion({fixture});+ expect(first.status, `${first.stdout}\n${first.stderr}`).toBe(0);+ const second = runPromotion({fixture});+ expect(second.status, `${second.stdout}\n${second.stderr}`).toBe(0);+ expect(second.stdout).toContain(+ 'Accepted visual bundle for PR #42 was already promoted.',+ );++ const final = path.join(fixture.root, 'duplicate-final');+ git(+ fixture.root,+ 'clone',+ '-q',+ '--branch',+ 'gh-pages',+ fixture.remote,+ final,+ );+ const manifest = JSON.parse(+ fs.readFileSync(+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),+ 'utf8',+ ),+ );+ expect(manifest.decisions).toHaveLength(1);+ expect(+ fs.readFileSync(+ path.join(final, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),+ ),+ ).toEqual(fixture.after);+ });+it.each([{name: 'a stale current pointer',@@ -346,7 +387,7 @@ describe('visual acceptance promotion workflow', () => {},{name: 'a superseded CI run',- latest: '124\\t1\\tcompleted',+ latest: {id: 124, run_attempt: 1, status: 'completed'},error: /not from the latest completed CI attempt/,},{@@ -365,7 +406,7 @@ describe('visual acceptance promotion workflow', () => {record.run.id = 124;writeJSON(acceptance, record);},- latest: '124\\t1\\tcompleted',+ latest: {id: 124, run_attempt: 1, status: 'completed'},error: /record identity does not match this merged head/,},{@@ -392,8 +433,8 @@ describe('visual acceptance promotion workflow', () => {it('does not consult ephemeral PR evidence during promotion', () => {const script = workflowStepScript('Verify and promote the baseline');- expect(script).toContain('current.json');- expect(script).toContain('LATEST_STATUS');+ expect(script).toContain('promotion-identity.mjs resolve-acceptance');+ expect(script).toContain('--expected-record-rel "$RECORD_REL"');expect(script).toContain('visual-acceptance.mjs promote');expect(script).not.toContain('visual-acceptance.mjs state');expect(script).not.toContain('/pr/');diff --git a/.github/scripts/visual-gate/workflow-concurrency.test.mjs b/.github/scripts/visual-gate/workflow-concurrency.test.mjsindex 499fc5357d..953d6ef9f3 100644--- a/.github/scripts/visual-gate/workflow-concurrency.test.mjs+++ b/.github/scripts/visual-gate/workflow-concurrency.test.mjs@@ -196,12 +196,136 @@ describe('visual acceptance workflow concurrency', () => {);});- it('uses the same head identity for post-merge promotion', () => {+ it('serializes normal, recovery, and manual publication without Actions cancellation', () => {const value = workflow('visual-acceptance-promote.yml');+ const manual = workflow('visual-baseline.yml');+ const helper =+ 'node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs';+ expect(value).toContain('workflow_dispatch:');+ expect(value).toContain("context.ref !== 'refs/heads/main'");+ expect(value).toContain('Checkout trusted current main');+ expect(value).toContain('Checkout the resolved merged result');+ expect(value).toContain('allow-unsafe-pr-checkout: true');+ expect(value.indexOf('compareCommitsWithBasehead')).toBeLessThan(+ value.indexOf('allow-unsafe-pr-checkout: true'),+ );+ expect(value).toContain('ref: main');+ for (const command of ['enqueue', 'wait', 'release']) {+ expect(value.match(new RegExp(`${helper} ${command}`, 'g'))).toHaveLength(+ 1,+ );+ expect(+ manual.match(new RegExp(`${helper} ${command}`, 'g')),+ ).toHaveLength(1);+ }+ expect(value).not.toContain('group: visual-baseline');+ expect(manual).not.toContain('group: visual-baseline');+ expect(value.indexOf('Recapture exactly the accepted shots')).toBeLessThan(+ value.indexOf('Wait for the baseline publication turn'),+ );+ expect(+ value.indexOf('Wait for the baseline publication turn'),+ ).toBeLessThan(value.indexOf('Verify and promote the baseline'));+ expect(value).toContain('--expected-record-rel "$RECORD_REL"');+ expect(workflow('pr-comment.yml')).toContain(+ 'Post-merge promotion does not join this cancellation group',+ );+ expect(+ manual.indexOf('Wait for the baseline publication turn'),+ ).toBeLessThan(manual.indexOf('Fetch the current baseline'));+ expect(workflow('release-gate.yml')).toContain(+ "grep -Ev '/(baseline|latest|publication-queue)/$'",+ );expect(value).toContain(- 'group: visual-acceptance-head-${{ github.event.pull_request.head.repo.id }}-${{ github.event.pull_request.head.ref }}',+ "context.eventName === 'workflow_dispatch' ? 'true' : 'false'",+ );+ });++ it('projects every known validation or publication failure from an always-running job', () => {+ const value = workflow('visual-acceptance-promote.yml');+ const status = value.slice(value.indexOf(' project-status:'));++ expect(status).toContain('if: always()');+ expect(status).toContain('statuses: write');+ expect(status).toContain('needs: [resolve, promote]');+ expect(status).toContain('needs.resolve.outputs.failure_description');+ expect(status).toContain('needs.promote.outputs.failure_description');+ expect(status).toContain('promotionStatusProjection');+ expect(status).toContain('target_url: process.env.TARGET_URL');+ expect(status).toContain("if (projection.state === 'failure')");+ expect(status).toContain('core.setFailed(projection.description)');+ expect(value.match(/core\.setOutput\('head_sha'/g)).toHaveLength(1);+ expect(value.indexOf('compareCommitsWithBasehead')).toBeLessThan(+ value.indexOf("core.setOutput('head_sha'"),+ );+ expect(value).toContain('core.setFailed(failure.description)');+ const beforeStatus = value.slice(0, value.indexOf(' project-status:'));+ expect(beforeStatus).toContain("state: 'pending'");+ expect(beforeStatus).not.toContain("state: 'success'");+ expect(beforeStatus).not.toContain("state: 'failure'");+ const promoteJob = value.slice(+ value.indexOf(' promote:'),+ value.indexOf(' project-status:'),+ );+ expect(promoteJob).toContain(+ "needs.resolve.outputs.acceptance_found == 'true'",+ );+ expect(+ promoteJob.slice(0, promoteJob.indexOf(' runs-on:')),+ ).not.toContain('mutation_deferred');+ expect(promoteJob).toContain('Confirm trusted active-retry deferral');+ expect(promoteJob).toContain('deferred=true');+ expect(promoteJob).toContain("if: steps.defer.outputs.deferred != 'true'");+ expect(value).toContain(+ "mutation_deferred: ${{ steps.defer.outputs.deferred == 'true' || steps.acceptance.outputs.deferred == 'true' || steps.promote.outputs.deferred == 'true' }}",+ );+ expect(status).toContain(+ "MUTATION_DEFERRED: ${{ needs.promote.outputs.mutation_deferred == 'true' }}",+ );+ expect(status).not.toContain('needs.resolve.outputs.mutation_deferred');+ const projectionCall = status.slice(+ status.indexOf('const projection = promotionStatusProjection({'),+ );+ expect(projectionCall).toContain(+ 'promotionResult: recoveryOperationResult({',+ );+ expect(projectionCall).toContain(+ 'mutationDeferred: process.env.MUTATION_DEFERRED',+ );+ expect(projectionCall).toContain(+ 'failureDescription: process.env.FAILURE_DESCRIPTION',+ );+ });++ it('marks success only after publication, gate dispatch, and lock release finish', () => {+ const value = workflow('visual-acceptance-promote.yml');+ const gate = value.slice(+ value.indexOf(' - name: Run a fresh release gate'),+ value.indexOf(' - name: Release the baseline publication turn'),+ );+ const release = value.slice(+ value.indexOf(' - name: Release the baseline publication turn'),+ value.indexOf(' - name: Mark trusted recovery complete'),+ );+ const complete = value.slice(+ value.indexOf(' - name: Mark trusted recovery complete'),+ value.indexOf(' project-status:'),+ );++ expect(value).toContain('publication_confirmed=true');+ expect(gate).toContain(+ "steps.promote.outputs.publication_confirmed == 'true'",+ );+ expect(gate).toContain('fresh release gate dispatch failed');+ expect(release).toContain('if: always()');+ expect(release).toContain('lock release failed');+ expect(complete).toContain("steps.gate.outcome == 'success'");+ expect(complete).toContain("steps.release.outcome == 'success'");+ expect(complete).toContain('recovery_complete=true');+ expect(value).toContain(+ 'RECOVERY_COMPLETE: ${{ needs.promote.outputs.recovery_complete }}',);- expect(value).not.toContain('visual-acceptance-pr-');+ expect(value).toContain('recoveryOperationResult({');});});diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.ymlindex d1573f1b2f..63a740c7eb 100644--- a/.github/workflows/pr-comment.yml+++ b/.github/workflows/pr-comment.yml@@ -25,8 +25,11 @@ on:permissions: {}# The event already carries a stable head-repository/branch identity. Acquire-# this shared lock before resolving the PR so a rerun can cancel any older-# acceptance, report publication, or promotion mutation for the same head.+# this shared lock before resolving the PR so a rerun can cancel older+# invalidation, report-publication, or acceptance mutations for the same head.+# Post-merge promotion does not join this cancellation group: it serializes+# durably with every baseline publisher, then recaptures the merged commit and+# requires its canonical pixels to match the latest completed accepted CI.concurrency:group: visual-acceptance-head-${{ github.event.workflow_run.head_repository.id }}-${{ github.event.workflow_run.head_branch }}cancel-in-progress: ${{ github.event.action == 'requested' || github.event.action == 'in_progress' }}diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.ymlindex 5d499612f3..50723d50a8 100644--- a/.github/workflows/release-gate.yml+++ b/.github/workflows/release-gate.yml@@ -300,7 +300,7 @@ jobs:# Keep the twenty most recent run directories; the report images are# only useful while the change they describe is still a live question.ls -1d /tmp/gh-pages/visual-gate/*/ 2>/dev/null \- | grep -Ev '/(baseline|latest)/$' \+ | grep -Ev '/(baseline|latest|publication-queue)/$' \| sort -V | head -n -20 | xargs -r rm -rfcd /tmp/gh-pagesdiff --git a/.github/workflows/visual-acceptance-promote.yml b/.github/workflows/visual-acceptance-promote.ymlindex 1e758d1077..e0dc4b00ec 100644--- a/.github/workflows/visual-acceptance-promote.yml+++ b/.github/workflows/visual-acceptance-promote.yml@@ -1,9 +1,8 @@# Copyright (c) Meta Platforms, Inc. and affiliates.# Promote a PR acceptance only after the merged commit reproduces every reviewed-# AFTER frame. The job is serialized with manual baseline promotion, and each-# key carries its baseline preimage hash so concurrent decisions cannot overwrite-# one another silently.+# AFTER frame. Normal closed-PR promotion and explicit recovery both resolve+# identity from GitHub and converge on this one trusted promotion job.name: Visual acceptance promotion@@ -11,71 +10,301 @@ on:pull_request_target:branches: ['main']types: [closed]+ workflow_dispatch:+ inputs:+ pr_number:+ description: 'Merged PR whose immutable visual acceptance should be retried'+ required: truepermissions: {}-concurrency:- # Shares the head-branch lock with rerun invalidation and acceptance. A new- # requested run cancels an older promotion before it can publish stale pixels;- # cross-PR baseline races are rejected by preimage hashes and push retries.- group: visual-acceptance-head-${{ github.event.pull_request.head.repo.id }}-${{ github.event.pull_request.head.ref }}- cancel-in-progress: false-jobs:+ resolve:+ if: >-+ github.event_name == 'workflow_dispatch' ||+ github.event.pull_request.merged == true+ runs-on: ubuntu-slim+ timeout-minutes: 5+ permissions:+ actions: read+ contents: read+ pull-requests: read+ outputs:+ pr: ${{ steps.resolve.outputs.pr }}+ head_sha: ${{ steps.resolve.outputs.head_sha }}+ merge_sha: ${{ steps.resolve.outputs.merge_sha }}+ recovery: ${{ steps.resolve.outputs.recovery }}+ validation_ok: ${{ steps.resolve.outputs.identity_valid == 'true' && steps.acceptance.outputs.validation_ok == 'true' }}+ acceptance_found: ${{ steps.acceptance.outputs.found }}+ mutation_deferred: ${{ steps.acceptance.outputs.deferred }}+ deferred_description: ${{ steps.acceptance.outputs.deferred_description }}+ record_rel: ${{ steps.acceptance.outputs.record_rel }}+ failure_description: ${{ steps.acceptance.outputs.failure_description || steps.resolve.outputs.failure_description }}+ steps:+ - name: Checkout trusted current main+ uses: actions/checkout@v7+ with:+ ref: main++ - name: Resolve trusted PR identity+ id: resolve+ uses: actions/github-script@v9+ env:+ REQUESTED_PR: ${{ github.event_name == 'workflow_dispatch' && inputs.pr_number || github.event.pull_request.number }}+ with:+ retries: 3+ script: |+ const {pathToFileURL} = require('node:url');+ const {+ promotionFailure,+ resolvePullRequestIdentity,+ } = await import(+ pathToFileURL(`${process.env.GITHUB_WORKSPACE}/.github/scripts/visual-gate/lib/promotion-identity.mjs`).href,+ );+ if (+ context.eventName === 'workflow_dispatch' &&+ context.ref !== 'refs/heads/main'+ ) {+ core.setFailed('Recovery must be dispatched from main.');+ return;+ }+ const {owner, repo} = context.repo;+ const requestedPr = Number(process.env.REQUESTED_PR);+ if (!Number.isSafeInteger(requestedPr) || requestedPr <= 0) {+ core.setFailed('Recovery requires a positive integer PR number.');+ return;+ }+ let pull;+ try {+ ({data: pull} = await github.rest.pulls.get({+ owner,+ repo,+ pull_number: requestedPr,+ }));+ } catch (error) {+ core.setFailed(`Could not resolve PR #${requestedPr}: ${error.message}`);+ return;+ }+ try {+ resolvePullRequestIdentity({+ pull,+ requestedPr,+ repository: `${owner}/${repo}`,+ compareStatus: 'identical',+ });+ const {data: comparison} =+ await github.rest.repos.compareCommitsWithBasehead({+ owner,+ repo,+ basehead: `${pull.merge_commit_sha}...main`,+ });+ const identity = resolvePullRequestIdentity({+ pull,+ requestedPr,+ repository: `${owner}/${repo}`,+ compareStatus: comparison.status,+ });+ core.setOutput('pr', String(identity.pr));+ core.setOutput('head_sha', identity.headSha);+ core.setOutput('merge_sha', identity.mergeSha);+ core.setOutput('identity_valid', 'true');+ core.setOutput(+ 'recovery',+ context.eventName === 'workflow_dispatch' ? 'true' : 'false',+ );+ } catch (error) {+ const failure = promotionFailure(error);+ core.setOutput('identity_valid', 'false');+ core.setOutput('failure_code', failure.code);+ core.setOutput('failure_description', failure.description);+ core.setFailed(failure.description);+ }++ - name: Setup trusted Node+ uses: actions/setup-node@v6+ with:+ node-version-file: .nvmrc++ - name: Resolve the immutable acceptance+ id: acceptance+ if: steps.resolve.outputs.identity_valid == 'true'+ env:+ GH_TOKEN: ${{ github.token }}+ PR_NUMBER: ${{ steps.resolve.outputs.pr }}+ HEAD_SHA: ${{ steps.resolve.outputs.head_sha }}+ RECOVERY: ${{ steps.resolve.outputs.recovery }}+ run: |+ set -eu+ PAGES="$RUNNER_TEMP/visual-acceptance-pages"+ git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages \+ "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$PAGES"+ git -C "$PAGES" sparse-checkout set \+ "visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"+ MISSING_OK=false+ if [ "$RECOVERY" != 'true' ]; then MISSING_OK=true; fi+ RESOLVED=$(node .github/scripts/visual-gate/lib/promotion-identity.mjs resolve-acceptance \+ --pages "$PAGES" \+ --pr "$PR_NUMBER" \+ --head "$HEAD_SHA" \+ --missing-ok "$MISSING_OK")+ OK=$(printf '%s' "$RESOLVED" | jq -r '.ok')+ if [ "$OK" != 'true' ]; then+ {+ echo "validation_ok=false"+ echo "found=false"+ echo "failure_description=$(printf '%s' "$RESOLVED" | jq -er '.description')"+ } >> "$GITHUB_OUTPUT"+ exit 0+ fi+ FOUND=$(printf '%s' "$RESOLVED" | jq -r '.found')+ DEFERRED=$(printf '%s' "$RESOLVED" | jq -r '.deferred // false')+ {+ echo "validation_ok=true"+ echo "found=$FOUND"+ echo "deferred=$DEFERRED"+ } >> "$GITHUB_OUTPUT"+ if [ "$DEFERRED" = 'true' ]; then+ echo "deferred_description=$(printf '%s' "$RESOLVED" | jq -er '.deferredDescription')" >> "$GITHUB_OUTPUT"+ fi+ if [ "$FOUND" != 'true' ]; then+ echo "No visual acceptance was recorded for this merged head."+ exit 0+ fi+ echo "record_rel=$(printf '%s' "$RESOLVED" | jq -er '.recordRel')" >> "$GITHUB_OUTPUT"+promote:- if: github.event.pull_request.merged == true+ needs: resolve+ if: >-+ needs.resolve.outputs.validation_ok == 'true' &&+ needs.resolve.outputs.acceptance_found == 'true'runs-on: 2-core-ubuntu-arm- timeout-minutes: 20+ timeout-minutes: 90permissions:actions: writecontents: writestatuses: write+ outputs:+ recovery_complete: ${{ steps.complete.outputs.recovery_complete }}+ mutation_deferred: ${{ steps.defer.outputs.deferred == 'true' || steps.acceptance.outputs.deferred == 'true' || steps.promote.outputs.deferred == 'true' }}+ deferred_description: ${{ steps.defer.outputs.deferred_description || steps.acceptance.outputs.deferred_description || steps.promote.outputs.deferred_description }}+ failure_description: ${{ steps.acceptance.outputs.failure_description || steps.promote.outputs.failure_description || steps.gate.outputs.failure_description || steps.release.outputs.failure_description }}steps:- - name: Checkout the merged result+ - name: Checkout trusted current mainuses: actions/checkout@v7with:- ref: ${{ github.event.pull_request.merge_commit_sha }}+ ref: main- - name: Find an acceptance for the merged head+ - name: Setup trusted Node and pnpm+ uses: ./.github/actions/setup+ with:+ install: 'false'++ - name: Confirm trusted active-retry deferral+ id: defer+ if: needs.resolve.outputs.mutation_deferred == 'true'+ env:+ DEFERRED_DESCRIPTION: ${{ needs.resolve.outputs.deferred_description }}+ run: |+ set -eu+ test -n "$DEFERRED_DESCRIPTION"+ {+ echo "deferred=true"+ echo "deferred_description=$DEFERRED_DESCRIPTION"+ } >> "$GITHUB_OUTPUT"++ - name: Mark trusted promotion pending+ if: steps.defer.outputs.deferred != 'true'+ uses: actions/github-script@v9+ env:+ HEAD_SHA: ${{ needs.resolve.outputs.head_sha }}+ with:+ retries: 3+ script: |+ await github.rest.repos.createCommitStatus({+ ...context.repo,+ sha: process.env.HEAD_SHA,+ context: 'visual-acceptance',+ state: 'pending',+ description: 'Trusted post-merge visual promotion is running.',+ target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,+ });++ - name: Queue baseline publication+ id: queue+ if: steps.defer.outputs.deferred != 'true'+ env:+ GH_TOKEN: ${{ github.token }}+ run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs enqueue++ - name: Load and verify the immutable acceptanceid: acceptance+ if: steps.defer.outputs.deferred != 'true'env:GH_TOKEN: ${{ github.token }}- PR_NUMBER: ${{ github.event.pull_request.number }}- HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ PR_NUMBER: ${{ needs.resolve.outputs.pr }}+ HEAD_SHA: ${{ needs.resolve.outputs.head_sha }}+ EXPECTED_RECORD_REL: ${{ needs.resolve.outputs.record_rel }}run: |set -euPAGES="$RUNNER_TEMP/visual-acceptance-pages"- git clone --depth=1 --single-branch --branch gh-pages \+ git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages \"https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$PAGES"- ROOT="$PAGES/visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"- POINTER="$ROOT/current.json"- if [ ! -f "$POINTER" ]; then- echo "No visual acceptance was recorded for this merged head."- echo "found=false" >> "$GITHUB_OUTPUT"- exit 0- fi- RECORD_REL=$(jq -r '.record // empty' "$POINTER")- if ! printf '%s' "$RECORD_REL" | grep -Eq '^[0-9]+/[0-9]+/acceptance\.json$'; then- echo "::error::Visual acceptance pointer is invalid"+ git -C "$PAGES" sparse-checkout set \+ "visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"+ RESOLVED=$(node .github/scripts/visual-gate/lib/promotion-identity.mjs resolve-acceptance \+ --pages "$PAGES" \+ --pr "$PR_NUMBER" \+ --head "$HEAD_SHA" \+ --missing-ok false \+ --expected-record-rel "$EXPECTED_RECORD_REL")+ OK=$(printf '%s' "$RESOLVED" | jq -r '.ok')+ if [ "$OK" != 'true' ]; then+ DESCRIPTION=$(printf '%s' "$RESOLVED" | jq -er '.description')+ echo "failure_description=$DESCRIPTION" >> "$GITHUB_OUTPUT"+ echo "::error::$(printf '%s' "$RESOLVED" | jq -er '.message')"exit 1fi- RECORD="$ROOT/$RECORD_REL"- if [ ! -f "$RECORD" ]; then- echo "::error::Visual acceptance record is missing"- exit 1+ FOUND=$(printf '%s' "$RESOLVED" | jq -r '.found')+ DEFERRED=$(printf '%s' "$RESOLVED" | jq -r '.deferred // false')+ {+ echo "found=$FOUND"+ echo "deferred=$DEFERRED"+ } >> "$GITHUB_OUTPUT"+ if [ "$DEFERRED" = 'true' ]; then+ {+ echo "found=false"+ echo "deferred_description=$(printf '%s' "$RESOLVED" | jq -er '.deferredDescription')"+ } >> "$GITHUB_OUTPUT"+ exit 0fi{- echo "found=true"- echo "record=$RECORD"- echo "record_rel=$RECORD_REL"+ echo "record=$(printf '%s' "$RESOLVED" | jq -er '.recordPath')"+ echo "record_rel=$(printf '%s' "$RESOLVED" | jq -er '.recordRel')"} >> "$GITHUB_OUTPUT"- - name: Setup Node and pnpm+ - name: Checkout the resolved merged resultif: steps.acceptance.outputs.found == 'true'- uses: ./.github/actions/setup+ uses: actions/checkout@v7+ with:+ ref: ${{ needs.resolve.outputs.merge_sha }}+ path: .visual-merged-source+ # The read-only resolver proved this exact commit is reachable from+ # current main before the privileged job started. Fork PR merges need+ # checkout's explicit opt-in even for that trusted merged commit.+ allow-unsafe-pr-checkout: true++ - name: Install trusted visual dependencies+ if: steps.acceptance.outputs.found == 'true'+ run: pnpm install --frozen-lockfile- - name: Build the merged Storybook+ - name: Install merged-result dependenciesif: steps.acceptance.outputs.found == 'true'+ working-directory: .visual-merged-source+ run: pnpm install --frozen-lockfile++ - name: Build the resolved merged Storybook+ if: steps.acceptance.outputs.found == 'true'+ working-directory: .visual-merged-sourcerun: pnpm build && pnpm -F @astryxdesign/storybook build- name: Install Chromium@@ -85,7 +314,7 @@ jobs:- name: Recapture exactly the accepted shotsif: steps.acceptance.outputs.found == 'true'env:- GITHUB_SHA: ${{ github.event.pull_request.merge_commit_sha }}+ GITHUB_SHA: ${{ needs.resolve.outputs.merge_sha }}ACCEPTANCE: ${{ steps.acceptance.outputs.record }}run: |set -eu@@ -93,55 +322,61 @@ jobs:--acceptance "$ACCEPTANCE" \--output accepted-plan.jsonnode .github/scripts/visual-gate/gate.mjs capture \- --storybook-dir apps/storybook/dist \+ --storybook-dir .visual-merged-source/apps/storybook/dist \--out .visual-merged \--plan-file accepted-plan.json+ - name: Wait for the baseline publication turn+ if: steps.acceptance.outputs.found == 'true'+ env:+ GH_TOKEN: ${{ github.token }}+ run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs wait+- name: Verify and promote the baselineid: promoteif: steps.acceptance.outputs.found == 'true'env:GH_TOKEN: ${{ github.token }}- PR_NUMBER: ${{ github.event.pull_request.number }}- HEAD_SHA: ${{ github.event.pull_request.head.sha }}- MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}+ PR_NUMBER: ${{ needs.resolve.outputs.pr }}+ HEAD_SHA: ${{ needs.resolve.outputs.head_sha }}+ MERGE_SHA: ${{ needs.resolve.outputs.merge_sha }}RECORD_REL: ${{ steps.acceptance.outputs.record_rel }}run: |set -euREPO_URL="https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"PAGES="$RUNNER_TEMP/visual-promote-pages"- RECORD="visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}/${RECORD_REL}"for attempt in 1 2 3 4 5; dorm -rf "$PAGES"- git clone --depth=1 --single-branch --branch gh-pages "$REPO_URL" "$PAGES"- CURRENT_REL=$(jq -r '.record // empty' \- "$PAGES/visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}/current.json")- if [ "$CURRENT_REL" != "$RECORD_REL" ]; then- echo "::error::A newer visual acceptance superseded the reviewed record"- exit 1- fi- ACCEPTED_IDENTITY=$(jq -er '[.pr, .headSha, .run.id, .run.attempt] | @tsv' \- "$PAGES/$RECORD")- IFS=$'\t' read -r ACCEPTED_PR ACCEPTED_HEAD ACCEPTED_RUN ACCEPTED_ATTEMPT <<< "$ACCEPTED_IDENTITY"- if [ "$ACCEPTED_PR" != "$PR_NUMBER" ] || \- [ "$ACCEPTED_HEAD" != "$HEAD_SHA" ] || \- [ "$RECORD_REL" != "${ACCEPTED_RUN}/${ACCEPTED_ATTEMPT}/acceptance.json" ]; then- echo "::error::Visual acceptance record identity does not match this merged head"+ git clone --depth=1 --filter=blob:none --sparse --single-branch --branch gh-pages \+ "$REPO_URL" "$PAGES"+ git -C "$PAGES" sparse-checkout set \+ visual-gate/baseline \+ "visual-gate/acceptances/${PR_NUMBER}/${HEAD_SHA}"+ RESOLVED=$(node .github/scripts/visual-gate/lib/promotion-identity.mjs resolve-acceptance \+ --pages "$PAGES" \+ --pr "$PR_NUMBER" \+ --head "$HEAD_SHA" \+ --missing-ok false \+ --expected-record-rel "$RECORD_REL")+ OK=$(printf '%s' "$RESOLVED" | jq -r '.ok')+ if [ "$OK" != 'true' ]; then+ DESCRIPTION=$(printf '%s' "$RESOLVED" | jq -er '.description')+ echo "failure_description=$DESCRIPTION" >> "$GITHUB_OUTPUT"+ echo "::error::$(printf '%s' "$RESOLVED" | jq -er '.message')"exit 1fi- LATEST=$(gh api \- "repos/${GITHUB_REPOSITORY}/actions/runs?event=pull_request&head_sha=${HEAD_SHA}&per_page=100" \- --jq '[.workflow_runs[] | select(.name == "CI")][0] | [.id, .run_attempt, .status] | @tsv')- IFS=$'\t' read -r LATEST_RUN LATEST_ATTEMPT LATEST_STATUS <<< "$LATEST"- if [ "$LATEST_RUN" != "$ACCEPTED_RUN" ] || \- [ "$LATEST_ATTEMPT" != "$ACCEPTED_ATTEMPT" ] || \- [ "$LATEST_STATUS" != "completed" ]; then- echo "::error::Accepted evidence is not from the latest completed CI attempt"- exit 1+ DEFERRED=$(printf '%s' "$RESOLVED" | jq -r '.deferred // false')+ if [ "$DEFERRED" = 'true' ]; then+ {+ echo "deferred=true"+ echo "deferred_description=$(printf '%s' "$RESOLVED" | jq -er '.deferredDescription')"+ } >> "$GITHUB_OUTPUT"+ exit 0fi+ RECORD=$(printf '%s' "$RESOLVED" | jq -er '.recordPath')node .github/scripts/visual-gate/visual-acceptance.mjs promote \--pages "$PAGES" \- --acceptance "$PAGES/$RECORD" \+ --acceptance "$RECORD" \--capture .visual-merged \--merge-sha "$MERGE_SHA"git -C "$PAGES" config user.name "github-actions[bot]"@@ -149,41 +384,123 @@ jobs:git -C "$PAGES" add visual-gate/baselineif git -C "$PAGES" diff --cached --quiet; thenecho "Baseline already contains the accepted pixels."+ echo "publication_confirmed=true" >> "$GITHUB_OUTPUT"exit 0figit -C "$PAGES" commit -m "visual baseline: accepted PR #${PR_NUMBER}"if git -C "$PAGES" push origin gh-pages; then+ echo "publication_confirmed=true" >> "$GITHUB_OUTPUT"exit 0fisleep $((attempt * 2))done+ echo "failure_description=Merged pixels did not promote to the visual baseline." >> "$GITHUB_OUTPUT"echo "::error::Could not promote the accepted baseline after 5 attempts"exit 1- name: Run a fresh release gate- if: steps.promote.outcome == 'success'+ id: gate+ if: steps.promote.outputs.publication_confirmed == 'true'uses: actions/github-script@v9with:retries: 3script: |- await github.rest.actions.createWorkflowDispatch({- ...context.repo,- workflow_id: 'release-gate.yml',- ref: context.payload.repository.default_branch,- });+ try {+ await github.rest.actions.createWorkflowDispatch({+ ...context.repo,+ workflow_id: 'release-gate.yml',+ ref: context.payload.repository.default_branch,+ });+ } catch (error) {+ core.setOutput(+ 'failure_description',+ 'Baseline published, but the fresh release gate dispatch failed.',+ );+ core.setFailed(error.message);+ }- - name: Mark a post-merge verification failure- if: failure() && steps.acceptance.outputs.found == 'true'+ - name: Release the baseline publication turn+ id: release+ if: always() && steps.defer.outputs.deferred != 'true'+ env:+ GH_TOKEN: ${{ github.token }}+ run: |+ set -eu+ if ! OUTPUT=$(node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs release 2>&1); then+ echo "failure_description=Baseline publication finished, but lock release failed." >> "$GITHUB_OUTPUT"+ echo "::error::$OUTPUT"+ exit 1+ fi+ printf '%s\n' "$OUTPUT"++ - name: Mark trusted recovery complete+ id: complete+ if: >-+ always() &&+ steps.promote.outputs.publication_confirmed == 'true' &&+ steps.gate.outcome == 'success' &&+ steps.release.outcome == 'success'+ run: echo "recovery_complete=true" >> "$GITHUB_OUTPUT"++ project-status:+ needs: [resolve, promote]+ if: always() && needs.resolve.outputs.head_sha != ''+ runs-on: ubuntu-slim+ timeout-minutes: 5+ permissions:+ contents: read+ statuses: write+ steps:+ - name: Checkout trusted current main+ uses: actions/checkout@v7+ with:+ ref: main++ - name: Project the final visual acceptance statususes: actions/github-script@v9env:- HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ HEAD_SHA: ${{ needs.resolve.outputs.head_sha }}+ VALIDATION_OK: ${{ needs.resolve.outputs.validation_ok }}+ ACCEPTANCE_FOUND: ${{ needs.resolve.outputs.acceptance_found }}+ JOB_RESULT: ${{ needs.promote.result }}+ RECOVERY_COMPLETE: ${{ needs.promote.outputs.recovery_complete }}+ MUTATION_DEFERRED: ${{ needs.promote.outputs.mutation_deferred == 'true' }}+ DEFERRED_DESCRIPTION: ${{ needs.promote.outputs.deferred_description }}+ FAILURE_DESCRIPTION: ${{ needs.resolve.outputs.failure_description || needs.promote.outputs.failure_description }}+ TARGET_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}with:retries: 3script: |+ const {pathToFileURL} = require('node:url');+ const {+ promotionStatusProjection,+ recoveryOperationResult,+ } = await import(+ pathToFileURL(`${process.env.GITHUB_WORKSPACE}/.github/scripts/visual-gate/lib/promotion-identity.mjs`).href,+ );+ const projection = promotionStatusProjection({+ headKnown: true,+ validationOk: process.env.VALIDATION_OK === 'true',+ acceptanceFound: process.env.ACCEPTANCE_FOUND === 'true',+ promotionResult: recoveryOperationResult({+ jobResult: process.env.JOB_RESULT,+ recoveryComplete: process.env.RECOVERY_COMPLETE === 'true',+ mutationDeferred: process.env.MUTATION_DEFERRED === 'true',+ failureDescription: process.env.FAILURE_DESCRIPTION,+ }),+ mutationDeferred: process.env.MUTATION_DEFERRED === 'true',+ deferredDescription: process.env.DEFERRED_DESCRIPTION,+ failureDescription: process.env.FAILURE_DESCRIPTION,+ });+ if (!projection) return;await github.rest.repos.createCommitStatus({...context.repo,sha: process.env.HEAD_SHA,context: 'visual-acceptance',- state: 'failure',- description: 'Merged pixels did not promote to the visual baseline.',+ state: projection.state,+ description: projection.description,+ target_url: process.env.TARGET_URL,});+ if (projection.state === 'failure') {+ core.setFailed(projection.description);+ }diff --git a/.github/workflows/visual-baseline.yml b/.github/workflows/visual-baseline.ymlindex c2b72941dd..2382421b42 100644--- a/.github/workflows/visual-baseline.yml+++ b/.github/workflows/visual-baseline.yml@@ -41,14 +41,10 @@ on:permissions: {}-concurrency:- group: visual-baseline- cancel-in-progress: false-jobs:promote:runs-on: ubuntu-slim- timeout-minutes: 20+ timeout-minutes: 90permissions:contents: writeactions: read # download-artifact from another run@@ -59,6 +55,11 @@ jobs:- name: Setup Node and pnpmuses: ./.github/actions/setup+ - name: Queue baseline publication+ env:+ GH_TOKEN: ${{ github.token }}+ run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs enqueue+- name: Download the capture being promoteduses: actions/download-artifact@v8with:@@ -67,6 +68,11 @@ jobs:github-token: ${{ github.token }}path: .visual-run+ - name: Wait for the baseline publication turn+ env:+ GH_TOKEN: ${{ github.token }}+ run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs wait+- name: Fetch the current baselinerun: |set -eu@@ -112,6 +118,12 @@ jobs:echo "::error::Could not push the updated baseline"exit 1+ - name: Release the baseline publication turn+ if: always()+ env:+ GH_TOKEN: ${{ github.token }}+ run: node .github/scripts/visual-gate/lib/baseline-publication-lock.mjs release+- name: Summaryrun: |{